skill-authoring

Skill Authoring

Create predictable Agent Skills through progressive disclosure, strong context pointers, checkable completion criteria, and single-sourced behavior.

Principles

• One skill per trigger phrase. A skill claims one thing a user would say. Two skills that would answer the same utterance are one skill; one skill that answers several unrelated utterances is several skills.
• Split by verb, never by noun. Verbs route; nouns collide. create and refine are two skills. Feature, Epic, and Story are one skill that infers the type, because the user often does not know which they want.
• Weight the split by what a misroute costs. Merge where a misroute produces a wrong write; split where it produces an obvious wrong answer. A read-only misroute is visible immediately; a wrong mutation is not.
• A skill needing a disambiguating sub-command is two skills. If the body opens by asking which mode the user wants, the router should have decided.
• Keep every-branch steps in SKILL.md; disclose branch-only reference behind a pointer that says when to read it.
• Keep references one level deep and independently usable.
• Keep descriptions below 1024 characters and skill bodies below 500 lines. The body limit governs SKILL.md only — measure the whole directory too, and settle it with the question the line count only hints at: which of these vocabularies does a caller have to learn? One trigger phrase commits the caller to one. Two skills in this pack reached 4,029 and 7,784 total lines while their SKILL.md files stayed comfortably compliant.
• Put deterministic validation and transformation in scripts.

Duplication

Judge it by layer, not by volume.

Prompt duplication is forbidden. When the same instructions, protocol, or domain rule would appear in two skills: extract a reference skill when nothing owns it, enforce the existing interface when a module already does, or document it once when it is a rule rather than a capability. Two callers is the threshold for extracting; one caller means it belongs inside its owner.

Code duplication is expected. Bundled scripts are self-contained so a skill can be installed alone. Copy the helper rather than reaching across a seam.

A rule the agent needs at runtime, in whatever repository it is working in, has to live in a skill. A repository's own AGENTS.md, decision records, and glossary govern work inside that checkout and do not travel with an installed skill — so a skill that cites them is broken for everyone who installs it.

Naming

A name describes its subject. Name by domain then verb, matching the trigger phrase the skill claims: <domain>-create, <domain>-review. Sibling skills use the same word for the same thing.

Ask what the skill is about, and let the answer decide the name. A skill about one product or system takes that product's name; a skill that is genuinely generic takes a generic name, even when it is published alongside product-specific ones. A prefix that overstates scope is worse than none — it promises knowledge the skill does not have.

Names are read by people, in a flat list where the folder is gone. Routing is a separate problem, solved by the description: keep the literal proper nouns — project keys, repository names, file names, tool names, an example identifier — because a literal token is the strongest anchor available.

That anchoring works on presence, so never put a literal in a description in order to disclaim it. "A key such as ABC-123 is not a sprint" makes the skill a candidate for exactly the request it is refusing. State the exclusion without the token: "works on a team and a board, never on a single issue key".

Working inside a host repository

Before designing a skill, read whatever conventions the repository states — typically AGENTS.md, a glossary, and any decision records. Those bind the skill you are about to write. They do not bind the skill once installed, so nothing you write into the skill may depend on being able to read them.

Where the repository publishes a collection, expect it to define: which skills are human-invoked, whether a name prefix applies, how skills compose, where the membership manifest lives, and what the tests protect. Follow its answers.

Interview dependency

Creating or interviewing for a skill requires an interview skill that stress-tests scope before drafting — /grilling in this collection. If the host cannot invoke it by name, stop before drafting anything and say that creation is gated on it. Audit and consolidation do not require it unless they open an interview.

Conditional references

Load exactly one branch. Its own pointers name any specification, description, architecture, script, or quality reference needed later.

• Read references/create.md to interview, draft, and review a new skill from scratch — "create a skill", "draft a SKILL.md", "package this expertise".
• Read references/audit.md to review, repair, or diagnose an existing skill — "why does this never trigger", "check this SKILL.md", "improve this skill".
• Read references/consolidation-guide.md to merge overlapping skills into fewer, or to test whether a merge already went too far. Finish through the Phase 5 review in references/create.md.

Completion

Work is complete when the selected branch's review checklist passes, every referenced resource resolves, no behavior remains duplicated under an old skill name, and every changed .py file passes the host linter.