Skill · meta · skill-creator
Write a skill
Create, edit, and evaluate Agent Skills (SKILL.md with progressive disclosure). Use whenever packaging how an agent should do a job, writing or improving a skill, optimizing a description for triggering, distilling a trace into a skill, or the user says skill, SKILL.md, skill-creator, progressive disclosure, or 'teach the agent this'.
GET /api/canon/skills/skill-creator?format=md
Anthropic skills are a three-level cache: name+description always in context, body on trigger, files on demand. Under-triggering is the default failure — the description is a search query, not a blurb.
When
Expertise should load sometimes, not always. The constitution (AGENTS.md) is too coarse; a prompt dump is too fat.
Do
- 01
Write the description first
What it does AND when to use it, including phrases a user will actually say. Pushy beats polite. Put all trigger context here, not in the body. Third person: 'This skill should be used when…'.
- 02
Body as a playbook
Imperative steps, a why, explicit don'ts. Keep SKILL.md under ~500 lines. Move depth to references/ and deterministic work to scripts/ (run, don't read).
- 03
One job
If two skills could fire, the model often picks none. Split or merge. Do not duplicate AGENTS.md.
- 04
Trigger-test
Five phrasings that should fire, two that should not. If it under-triggers, the description is wrong — not the body.
- 05
Distill from traces when you have them
The smallest skill that would have prevented a paid-for miss. Transcripts are not memory.
Don't
- Paste a treatise into AGENTS.md instead of a skill.
- Write a polite one-line description with no trigger phrases.
- ALWAYS/NEVER wallpaper. Explain why.
- Put secrets, repo-specific passwords, or malware in a skill.
Hard rules
- Frontmatter requires name (kebab-case) and description.
- Description = what + when + trigger contexts. Body = how.
- references/ loaded on demand; scripts/ executed without entering the window.
- Test descriptions against should-fire and should-not-fire prompts.
SKILL.md
---
name: review-pr
description: >
Review a git diff against the repo's test and style rules. Use when the user
asks to review a PR, a patch, or 'what did I just change' — not for writing
new features from scratch.
---
# Review a PR
## When
A patch exists. Tests are named in AGENTS.md.
## Do
1. Read AGENTS.md test commands.
2. git diff / the supplied patch. Do not read whole files unless the hunk needs them.
3. Run the test command. Compact failures.
4. Return: blockers, risks, nits — three lists.
## Don't
- Approve without running tests.
- Restyle unrelated files.
Refuse
- Unowned prompt — The policy lives in a framework black box you cannot diff, test, or revert.
- Context hoarding — Raw HTML, full CI logs, six PDFs, entire JSON envelopes stuffed 'just in case'. The goal is the first thing forgotten.
- Memory as unfiltered logs — Session transcripts stuffed into the next session. The user cannot inspect or delete them.
Load with this
Load next
Trigger tests
Should fire
- “Write a skill for reviewing PRs”
- “Package this workflow as SKILL.md”
- “The agent never loads our style guide — fix the skill”
- “skill-creator: distill this run”
- “How do I teach the agent our deploy process?”
Should not
- “Add a README section”
- “Explain what an LLM is”