skill-authoring

Skill Creator

Create skills that are short, reusable, and biased toward execution.

Core Rules

1. Optimize for another agent using the skill, not for a human reading documentation.
2. Keep SKILL.md small. Put details into references/, deterministic logic into scripts/, and templates into assets/.
3. Put trigger conditions in frontmatter description, not in the body.
4. Prefer procedures and selection rules over long explanations.
5. Source-ground every interface-specific claim against real code, help(...), or -h/--help before writing it into the skill.
6. Include only information another agent is unlikely to infer reliably from general knowledge.
7. Default to capability-first naming. Do not let a sample dataset, species, notebook title, or one published figure become the skill identity unless the workflow is truly specific to that artifact.
8. In generated skill documentation, prefer repo-relative paths or import paths. Do not bake local absolute source-code paths from one machine into SKILL.md or references/.
9. Keep reusable skill content environment-agnostic. Do not encode local environment names such as omictest into SKILL.md or references/; if local validation depends on them, keep that only in the review harness, acceptance harness, or calling prompt.
10. Treat local validation configuration as review-harness data, not as part of the reusable skill itself.
11. Do not generate a scripts/ directory by default. Add scripts only when they carry reusable deterministic logic or a necessary bounded smoke utility that would otherwise make the skill less reliable.

Skill Shape

Each skill should follow this structure:

skill-name/
├── SKILL.md
├── scripts/        # executable helpers for repeated or fragile steps
├── references/     # selectively loaded reference material
└── assets/         # templates, starter files, static resources

Use only the folders that are needed. Do not add extra docs like README.md, CHANGELOG.md, or process notes.