references/skill-authoring.md
GitHubSkill authoring spec
Read this before writing a harvested skill. It is a condensed version of the Agent Skills specification and best-practices, focused on what you need to produce a good, well-triggering, safe skill. Source: https://agentskills.io
Directory structure
<skill-name>/
├── SKILL.md # required: YAML frontmatter + Markdown body
├── references/ # optional: docs the agent loads on demand
├── assets/ # optional: templates, schemas, static resources
└── scripts/ # optional: executable code the agent can run
SKILL.md MUST live at the skill root. Only the root SKILL.md is parsed as a
skill — files with frontmatter inside references//assets/ are inert (safe to
use as templates).
Frontmatter
| Field | Required | Rules |
|---|---|---|
name |
yes | 1–64 chars, lowercase a-z/0-9/- only, no leading/trailing/--. Must equal the directory name. |
description |
yes | 1–1024 chars. Says what it does AND when to use it. Carries the entire triggering burden. |
license |
no | License name or a bundled file reference (e.g. MIT). |
compatibility |
no | ≤500 chars. Only if there are real environment requirements (tools, network, runtime). Most skills omit it. |
metadata |
no | Arbitrary string→string map (e.g. author, version). |
allowed-tools |
no | Space-separated pre-approved tools (experimental; support varies). Omit unless you have a reason. |
Minimal valid frontmatter:
---
name: my-skill
description: What it does and when to use it.
---
Writing the description (the most important field)
At startup the agent loads only name + description for every skill, and uses
the description to decide whether to load the body. Get this wrong and the skill
never fires (or fires when it shouldn't).
- Imperative + "when". "Use this skill when…", not "This skill does…".
- What + when, both. State the capability and the trigger situations.
- Be pushy about triggers. List the contexts it applies to, including when the user won't name the domain: "…even if they don't mention 'X'."
- Match user intent, not internals. Describe what the user is trying to do.
- Concise. A few sentences to a short paragraph. Hard limit 1024 chars.
# weak
description: Process CSV files.
# strong
description: >
Analyze CSV/TSV/Excel data — summary stats, derived columns, charts, cleaning.
Use when the user has a tabular data file and wants to explore, transform, or
visualize it, even if they don't explicitly say "CSV" or "analysis."
Body content
No required format, but favor this shape:
- One or two lines on what the skill is for.
- Procedure — numbered/checklist steps, with a clear default at each choice.
- A short worked example (input → command → output) when it helps.
- Gotchas — see below; often the highest-value part.
Calibrate prescriptiveness to fragility:
- Be exact for fragile/destructive/order-dependent steps ("run exactly this command, don't add flags").
- Give freedom + explain why where several approaches are valid.
- Provide a default, not a menu. Name one tool/approach; mention an alternative briefly as an escape hatch.
- Procedures over declarations. Teach how to approach the class of problem, not the answer to one instance — that's what makes it reusable.
Add what the agent lacks, omit what it knows
Spend tokens only on what the agent wouldn't get right on its own: project conventions, the specific commands/paths/tools, and non-obvious edge cases. Don't explain what a database or a deploy is. For each line ask: "Would the agent get this wrong without it?" If no, cut it.
Gotchas section (high value)
Concrete corrections to mistakes the agent will make otherwise — not generic
advice. Keep these in SKILL.md so they're read before the situation arises.
## Gotchas
- The `users` table uses soft deletes — queries need `WHERE deleted_at IS NULL`.
- The `/health` endpoint returns 200 even when the DB is down; use `/ready`.
- Creds live in env var `FOO_TOKEN` (see `lib/clients/foo-real.ts`), never in code.
Useful patterns (use the ones that fit)
- Checklist for multi-step workflows with dependencies.
- Validation loop: do the work → run a check → fix → repeat until it passes.
- Plan-validate-execute for batch/destructive ops.
- Output template when a specific format is required (agents pattern-match templates better than prose).
Progressive disclosure
- Keep
SKILL.mdunder 500 lines / ~5000 tokens. - Move long reference material to
references/, templates toassets/, reusable code toscripts/. - Reference them with relative paths, one level deep, and tell the agent
when to load each: "Read
references/api-errors.mdif the API returns a non-200." A generic "see references/" defeats the purpose.
Secrets safety (non-negotiable)
Harvested skills get committed and often open-sourced. Never write a secret value — no passwords, tokens, connection strings, API keys, or private endpoints. Record only where to find it: the env var name, the selector function, the MCP tool, the secret manager / vault entry. If you catch yourself pasting a value, replace it with its source.
Self-validation checklist (run before finishing)
- Promotion rule met: the skill records a passing check that verified the path, names the failure pattern it addresses, and lists ≥1 ruled-out dead-end. If any is missing, this shouldn't be a skill — stop and report it.
-
SKILL.mdexists at the skill root. -
namematches the directory name and the regex (lowercase, hyphen rules). -
descriptionis non-empty, ≤1024 chars, and states what + when. - Body is a generalized procedure, not a one-off answer.
- No secret values anywhere in the skill — only pointers to them.
-
SKILL.mdis under ~500 lines; long material is inreferences//assets/. - Relative file references are correct and one level deep.
Optional, if skills-ref is installed:
skills-ref validate <path-to-skill> checks frontmatter and naming.