Writing and improving agent skills: description as routing signal, progressive disclosure, token budgets, testing before shipping, and improving from repeated mistakes. Use when authoring, editing, or reviewing a skill.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# Skill authoring
A skill is instructions that route: the description selects it, the body runs it. Write for both, and test before shipping.
## Structure
- `SKILL.md` frontmatter: `name` (kebab-case, equal to the directory name) and `description`. Flags and loading rules: `guide://extensions`.
- Body: the procedure, imperative, in the fewest lines that stay complete. Lead with the steps; put the why in one clause where a step would look arbitrary without it.
- References (`references/*.md`, at most 3): deeper material only some tasks need. The body must stand alone without them. Template: `references/template.md`.
- Budgets: description 220 characters or less; body 120 lines and about 6 KB or less. Every session lists the description, so cut hard.
## The description is the routing signal
- It is the only text seen before a skill is read. It must contain the task vocabulary a user would actually type.
- Third person, one or two sentences: what the skill does, then "Use when ..." for the trigger.
- Test it: write three prompts that should select the skill and two that should not. If the description cannot separate them, rewrite it.
## Body rules
…
The line at the top of this page pins the label git:20261010.ee06e2b, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_bpuibb7gbnaubnni
GET https://markdownregistry.com/api/v1/resolve?ref=damianvtran/local-operator/skill-authoring
GET https://markdownregistry.com/api/v1/blob/84556a4a4d28a7a54d8916b33737667f8a6569cb2a3d7680363fda10fdf772cf
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
damianvtran/local-operator · local_operator/skills/builtin/browser-qa/SKILL.md · Testing web apps through a real browser: reconnaissance before acting, selector discovery, state capture, console…
damianvtran/local-operator · local_operator/skills/builtin/design-qa/SKILL.md · Deterministic design review for UI/UX on web and terminal screens: measure contrast, spacing, overlap, clipping and…
damianvtran/local-operator · local_operator/skills/builtin/financial-analysis/SKILL.md · Financial figures done carefully: periods and fiscal calendars, units and currencies, reconciliation, magnitude sanity…
damianvtran/local-operator · local_operator/skills/builtin/frontend-design/SKILL.md · Designing interfaces with a deliberate point of view: plan before pixels, avoid the generic-default look, typography…
damianvtran/local-operator · local_operator/skills/builtin/scheduling/SKILL.md · Scheduling across time zones: confirm times in the attendee's own zone, use IANA zone names, mind DST edges, buffers…
damianvtran/local-operator · local_operator/skills/builtin/test-driven-development/SKILL.md · Writing code with tests first: RED-GREEN-REFACTOR, reproduce bugs as failing tests before fixing, and avoid testing…
nyldn/claude-octopus · .claude/skills/skill-authoring/SKILL.md · Principles for writing skills that behave the same way every run — use when adding, editing, or reviewing a skill in…
nyldn/claude-octopus · skills/skill-authoring/SKILL.md · Principles for writing skills that behave the same way every run — use when adding, editing, or reviewing a skill in…
cbrock84/headcount · plugins/technology/skills/skill-authoring/SKILL.md · Writes and revises agent skills so they trigger at the right moments and give usable instruction when they do. Use this…
athola/claude-night-market · plugins/abstract/skills/skill-authoring/SKILL.md · Guide creating Claude Code skills with TDD and persuasion principles. Use for new skill development.
