Originally published at buyagentskills.com.
Short answer: A skill works when your agent picks it at the right moment and then follows it. Both depend on the SKILL.md. Write a description that says what the skill does and when to use it, keep the body short and in the order a person would work, move long reference material into separate files, and test with real prompts.
Written by the Buy Agent Skills team. Updated 17 November 2026.
New to the format? Start with what are agent skills.
The shape of a skill
A skill is a folder with a SKILL.md file. At the top is a small frontmatter block with a name and a description. Below is the instruction text. Optional files sit beside it, for example references/ for longer notes.
name: copy-editing
description: Tighten, proofread and review existing marketing copy. Use when the user asks to edit, improve, shorten or check copy for clarity or unproven claims.
# Copy editing
1. Ask for the audience and the goal if they are not given.
2. ...
The rules for those two fields (from the Agent Skills specification at agentskills.io, read 17 November 2026):
-
name: 1 to 64 characters, lowercase letters, numbers and hyphens only, no hyphen at the start or end, no double hyphens, and the same as the folder name. Socopy-editing/SKILL.mdhasname: copy-editing. -
description: 1 to 1024 characters, saying what the skill does and when to use it.
Claude Code treats name as optional and falls back to the folder name, but matching names keep one folder working in every tool.
1. Write the description for the agent, not for a catalog
The agent decides whether to use a skill mostly from its description. Two sentences: what it does, then "Use when ..." with the words a user would actually say.
- Weak:
Helps with copy. - Better:
Tighten, proofread and review existing marketing copy. Use when the user asks to edit, shorten or check copy for clarity or unproven claims.
The real copy-editing skill in our Marketing Copy Pack goes further: its description lists phrases people type, such as "tighten this" and "cut the fluff", and names the sibling skill to use for writing new copy instead.
If a skill never triggers, the description is the first thing to fix.
2. One skill, one job
A skill that covers pricing, SEO and email will trigger on none of them reliably. Split it. Our packs keep skills narrow, such as pricing, seo-audit and signup, so each description can be specific.
3. Keep the body short and ordered
Write the steps in the order someone would do the job. Lead with what to ask the user for, then what to produce, then how to check it. The spec recommends keeping SKILL.md under 500 lines; past that, you are probably carrying reference material that belongs in another file.
4. Put long reference material in separate files
Keep SKILL.md as the plan. Link to files in references/ for long checklists, examples and templates, and say when to read them. The agent then loads the extra text only when it is needed.
5. Ask for facts, never invent them
Good marketing skills tell the agent to ask for product facts, or read them from a shared context file, and to mark missing numbers as gaps. Our Marketing Copy Pack does this: claims that need proof are flagged, and missing numbers are left as marked gaps.
6. Be careful with scripts
If a skill ships scripts, say what each one does and why. Avoid network calls you do not need. Buyers will read them; see how to check a skill before installing.
7. Keep license notices
If you adapted someone else's skill, keep their license file and credit them. Do not call adapted work original.
8. Test with real prompts
Write 3 to 5 prompts a user would type, and what a good result contains. Run each in a fresh session and check that the skill loaded and the output matches. Our Marketing Copy Pack ships these as an evals/ folder, so buyers can repeat the check in their own setup. We list what we ran, and what we did not, on each pack page and on how we test.
Quick checklist
-
namematches the folder name;descriptionsays what it does and "use when" - One job per skill
- Steps in working order, body short
- Long material in
references/ - No invented facts; gaps marked
- Scripts explained, no needless network calls
- License file kept
- 3-5 test prompts run in a fresh session
FAQ
Where do skills go?
For Claude Code, .claude/skills/; for Codex, .agents/skills/. Steps are in how to install skills in Claude Code and Codex.
My skill never triggers. What now?
Rewrite the description with the exact words a user would say, then test again in a new session.
How long should a SKILL.md be?
As short as the job allows. Move long material to references/.
Do I need scripts?
No. Many useful skills are plain instructions.
See it in practice
You can read every SKILL.md in our packs before you use it. Start with the Marketing Copy Pack ($29) for three skills and their eval prompts, or the Marketing Foundations Pack ($39) for ten.
Independent product. Not affiliated with or endorsed by Anthropic or OpenAI.
Top comments (0)