| name | skill-authoring |
| description | Create and maintain agent skills with concise trigger metadata, judgement-aware guidance, progressive disclosure, and tested interfaces. Use when adding, refactoring, reviewing, or troubleshooting skills and their bundled scripts or references. |
Skill Authoring
Build skills that contribute context the model could not reliably infer on its
own. Prefer team or product knowledge, operational gotchas, safety boundaries,
and tested interfaces over generic advice.
Design principles
Let the model use judgement
Describe the outcome, relevant constraints, and local conventions. Avoid
absolute workflow rules, arbitrary thresholds, and fixed sequences unless a
safety property, external protocol, or repository policy genuinely requires
them.
When a constraint is necessary, explain the reason and scope so it does not
silently override the user's intent or surrounding project guidance.
Design interfaces, not exploration paths
For deterministic or fragile work, provide a script or tool with expressive
parameters, useful validation, and actionable errors. Document its contract
and discovery mechanism such as --help; do not enumerate every invocation
in SKILL.md.
Use examples only when they reveal semantics that the interface cannot express
clearly. Treat examples as illustrations, not templates the model must copy.
Use progressive disclosure
Skills load in three tiers:
- Frontmatter advertises what the skill does and when it applies.
SKILL.md supplies the shortest useful workflow and routing decisions.references/, scripts/, and assets/ provide details only when needed.
Keep references one level deep. Link them directly from SKILL.md and say when
to read each one. Long API recipes, exhaustive formats, platform-specific
syntax, troubleshooting catalogs, and extended examples usually belong in
references.
Do not repeat the harness
Do not restate tool schemas, global policies, ordinary coding knowledge, or
instructions already owned by another skill. Link to the owning skill or rely
on the tool description. One rule should have one authoritative home.
Preserve justified strictness
Low-freedom instructions remain appropriate for destructive actions,
credentials, financial changes, publication, protocol invariants, and other
high-cost failures. Make the boundary narrow and keep the mechanism
verifiable.
Structure
.agents/skills/<skill-name>/
├── SKILL.md
├── references/ # optional, loaded on demand
├── scripts/ # optional, executable interfaces
└── assets/ # optional, output resources
Required frontmatter:
---
name: skill-name
description: What the skill does. Use when the relevant trigger occurs.
---
name must match the parent directory and follow the Agent Skills
specification.description is always-loaded routing context: include capabilities and
triggers, but not the workflow.- Use
.agents/skills/ for cross-platform skills unless project guidance says
otherwise.
Authoring workflow
- Identify the non-obvious knowledge or reliable interface the skill adds.
- Check whether an existing skill, project rule, tool description, or script
already owns it.
- Choose the freedom level appropriate to the consequence of error.
- Write routing metadata, then a concise happy path and decision points.
- Move conditional or detailed material behind direct reference links.
- Test scripts and validate frontmatter and links.
- Re-read the skill and remove repetition, obvious advice, unnecessary
examples, and constraints that surrounding context can decide better.
Review questions
- Would a capable model know this without the skill?
- Does each absolute rule protect a real invariant?
- Could a parameterized interface replace prose or examples?
- Is conditional detail loaded only when its condition occurs?
- Does the skill defer to user intent and repository conventions where safe?
- Is another file the authoritative source for any repeated instruction?
- Can a reader discover every referenced file directly from
SKILL.md?
References
