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 =
namein the frontmatter. A mismatch is a failure. - Tests NEVER go under
skills/. The skill folder contains only what the agent loads. Tests go intests/<skill-name>/, fixtures intests/<skill-name>/fixtures/. - Diagrams also don't go under
skills/. If there are any, they go indocs/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.versionis 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.jsonversionmust matchpyproject.toml[project].version(currently both are2.66.0).
5. A skill has scripts/ — three mandatory accompanying things
tests/<name>/test_scripts.py(fixture attests/<name>/fixtures/).- An entry
[skills.<name>]intests/skill-requirements.toml. Usepackages = []if the script only uses the standard library — it still gets a clean environment, and CI runs exactly that set on every PR. - Add
python = "3.11"(or a suitable one) to the entry if the skill can't run on the default interpreter;uvwill 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
namein the frontmatter match exactly. - No
tests/, notest_*.pyanywhere underskills/<name>/. - Only 6 top-level fields per spec; everything else goes in
metadata. -
metadata.versionexists, is quoted, and has been bumped if an old skill was edited. -
metadatais a block mapping; theopenclaw/hermesblock is a nested mapping. -
uv run skills-ref validate skills/<name>pass. - If the collection version changed:
plugin.jsonmatchespyproject.toml. -
uv run --with pytest python -m pytest tests/_meta -qpass — this is a blocking CI gate. - If there is
scripts/: there istests/<name>/, there is[skills.<name>], andpython 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.pydoes NOT exist in the repo.AGENTS.mdhas a whole "Skill diagrams" section explaining how to run it withOPENROUTER_API_KEY, but.gitignorecontains the line/scripts/(with a/anchor at the start, deliberately, so it doesn't swallow the wrongskills/<name>/scripts/) so that directory has never been committed.findon 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 inscripts/is consequential: see the one-skill-one-process rule in 08. - Four skill documents (
docx,pdf,pptx,xlsx) are from Anthropic, vendored fromanthropics/skillsand tracked upstream. Editing them here goes against the flow —tests/_metastill 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.