SuperAPI AI Directory

dym-scientific-agent-skills-dong-gop-them-sua-skill

Coding & development

View repository

Updated 10-18 01:22

About this skill

Skill: dym-scientific-agent-skills-dong-gop-them-sua-skill — Contribution: add or edit a skill

CONTRIBUTION track. This file is for people who clone the skill repo itself to modify it. If you just want to use the skill, go back to 01.

Why use it: the repo has some implicit rules that CI enforces strictly and the validator reports errors that are very hard to understand (especially the strictyamlrule). This file is a checklist in the right order, so the PR doesn't get rejected for formal reasons. What it produces: a valid skills/<name>/ a valid tests/<name>/ if the skill has scripts/, an entry in tests/skill-requirements.toml, and a PR that passes the gate.


0. Should it be in this repo at all

AGENTS.md lists the types of rejected as usual:

  • General software engineering/code judgment skill — they compete for the choice slot in every task.
  • General infrastructure with a scientific example tacked on (vector database, cloud SDK) — accept one and you have to carry every competitor.
  • Broad "orchestrator" skill that specializes in routing to other skills — by design it overrides every specialist.
  • A second provider for a service that already has a skill.

In scope: a narrow skill for one research package/database/platform/workflow — scanpy, depmap, benchling-integration, experimental-design.

The shared skills that currently exist (docx, pdf, pptx, generate-image, markdown-mermaid-writing) are narrow output-format helpers, and AGENTS.md says outright they are not a precedent for expanding scope.

1. Layout

plugin.json                 # manifest Agent Plugins (repo root)
skills/<skill-name>/
├── SKILL.md        # BẮT BUỘC — file duy nhất bắt buộc
├── references/     # tuỳ chọn: tài liệu dài, chỉ nạp khi cần
├── scripts/        # tuỳ chọn: helper chạy được
└── assets/         # tuỳ chọn: template, tài nguyên tĩnh

Three absolute rules:

  • Folder name = name in the frontmatter. A mismatch is a failure.
  • Tests NEVER go under skills/. The skill folder contains only what the agent loads. Tests go in tests/<skill-name>/, fixtures in tests/<skill-name>/fixtures/.
  • Diagrams also don't go under skills/. If there are any, they go in docs/images/<skill-name>.png.

Tests point to the skill via an explicit anchor, not a relative path:

SKILL_ROOT = Path(__file__).resolve().parents[2] / "skills" / "<skill-name>"

2. Frontmatter — only 6 fields, no more

The spec defines a closedset. Any other top-level key is a validation error.

Field Required Constraint
name ✅ 1–64 characters, lowercase letters/digits/hyphens only, no leading/trailing/consecutive hyphens, must equal the folder name
description ✅ 1–1024 characters. Say what the skill does and when to use, along with trigger keywords. Write in the third person
license — license name or point to the accompanying license file
compatibility — maximum 500 characters, only environment requirements; if none, omit the field entirely
allowed-tools — space-separated string, for example Read Write Edit Bash. Not a YAML list, not commas
metadata — map string keys → values string. Required: metadata.version

Everything else — author, upstream version, review date, per-client config — goes into in metadata.

Three YAML traps that make a skill "disappear"

(a) Flow style JSON breaks the ENTIRE frontmatter. The validator uses strictyaml, which rejects JSON-style flow mapping/sequence. It's not failing one check — the whole frontmatter can't be parsed, name and description become unreadable, and the skill can't be registered.

# SAI — làm gãy validator
metadata: {"version": "1.1", "skill-author": "K-Dense Inc."}

# ĐÚNG
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.

(b) Scalars in metadata must be quoted if they look like a number/bool/date: version: "1.0", last-reviewed: "2026-07-23" — the spec requires them to be strings.

(c) metadata.openclaw and metadata.hermes are exceptions: keep them as nested mappings, not a JSON string. resolveOpenClawManifestBlock() of OpenClaw requires typeof candidate === "object"; a JSON string will silently disable dependency gating and credential injection. Nested mappings still pass skills-ref validate.

metadata:
  version: "1.1"
  skill-author: Exa
  openclaw:
    primaryEnv: EXA_API_KEY
    envVars:
      - name: EXA_API_KEY
        required: true
        description: Exa search API key.
  hermes:
    category: research

And: required_environment_variables top-level of Hermes can't be used in this repo — it fails the validator and, because strictyaml rejects the entire document, it drags name/description down with it. Declare credentials via compatibility and metadata.openclaw.envVars.

Gate requires / requires_toolsets failure will hide the skill from the agent, so only gate on things the skill truly cannot run without.

3. SKILL.md Template

---
name: skill-name
description: What the skill does and when an agent should use it, including the terms that should trigger it.
license: MIT
compatibility: Requires Python 3.12+ with <package> installed. Needs network access.
metadata:
  version: "1.0"
  skill-author: Your Name
---

# Skill Title

## When to use

Use this skill when...

## Workflow

1. ...

## Examples

...

Body rules:

  • Under 500 lines. CI warns when exceeded. Move long documentation into references/ so the agent only loads it when needed.
  • Include workflows, commands, runnable examples — not background explanations.
  • State packages, system dependencies, credentials, network requirements.
  • State scientific caveats and meaningful verification steps.
  • Push fragile or repeated logic into scripts/, don't make the agent rebuild it every time.
  • Never include secrets, API keys, private URLs, unpublished data.
  • Reference other files with relative paths from the skill root, at most one level deep.

4. Versioning

  • New skill: start at metadata.version: "1.0".
  • Editing an existing skill: bump in the same PR — minor for routine improvements ("1.2" → "1.3"), major only on breaking change or significant redesign ("1.9" → "2.0").
  • The test suite only checks metadata.version is present and quoted, it does not check the value — so bumping the version never drags test edits along.
  • If the version of collection changes, plugin.json version must match pyproject.toml [project].version (currently both are 2.66.0).

5. A skill has scripts/ — three mandatory accompanying things

  1. tests/<name>/test_scripts.py (fixture at tests/<name>/fixtures/).
  2. An entry [skills.<name>] in tests/skill-requirements.toml. Use packages = [] if the script only uses the standard library — it still gets a clean environment, and CI runs exactly that set on every PR.
  3. Add python = "3.11" (or a suitable one) to the entry if the skill can't run on the default interpreter; uv will download that interpreter when needed.

tests/_meta red if (1) or (2) is missing. If the package is completely uninstallable, record it in the [unavailable] section with the reason — the runner prints it so the gap surfaces in the test output.

6. Fix skills/ then what else to fix

  • docs/skills.md — reader-facing catalog, grouped by domain.
  • docs/examples.md — if a new skill changes an example workflow.
  • README.md — only when the repo-level numbers change (skill count, database count).

7. Checklist before opening a PR

Copied verbatim from AGENTS.md:

  • The directory name and name in the frontmatter match exactly.
  • No tests/, no test_*.py anywhere under skills/<name>/.
  • Only 6 top-level fields per spec; everything else goes in metadata.
  • metadata.version exists, is quoted, and has been bumped if an old skill was edited.
  • metadata is a block mapping; the openclaw/hermes block is a nested mapping.
  • uv run skills-ref validate skills/<name> pass.
  • If the collection version changed: plugin.json matches pyproject.toml.
  • uv run --with pytest python -m pytest tests/_meta -q pass — this is a blocking CI gate.
  • If there is scripts/: there is tests/<name>/, there is [skills.<name>], and python tests/run_all.py --isolated <name> pass.
  • If there is docs/images/<name>.png: labels spelled correctly, arrows pointing to the right place. Images are optional.
  • Examples and scripts tested, or clearly marked as illustrative.
  • No secrets, no private data; scan results clean or explained in the PR.

How to run each command in the checklist: 08-dong-gop-validate-test-scan.md.

Verified pitfalls

  • scripts/generate_skill_image.py does NOT exist in the repo. AGENTS.md has a whole "Skill diagrams" section explaining how to run it with OPENROUTER_API_KEY, but .gitignore contains the line /scripts/ (with a / anchor at the start, deliberately, so it doesn't swallow the wrong skills/<name>/scripts/) so that directory has never been committed. find on the clone tree: 0 results. Diagrams are optional and no there is no CI check — don't plan around this command.
  • 32 skills ship in one file scripts/_common.py. Naming the top-level module in scripts/ is consequential: see the one-skill-one-process rule in 08.
  • Four skill documents (docx, pdf, pptx, xlsx) are from Anthropic, vendored from anthropics/skills and tracked upstream. Editing them here goes against the flow — tests/_meta still reports red if the byte-identical copies (the OOXML tree; the shared AI schematic generator in five skills) drift apart, so they must be edited simultaneously.