How to Write Agent Skill from One Real Failure
Learn how to write agent skill from one repeated failure: structure SKILL.md, tune the description line wey controls when e fires, and test am properly.
Write your own agent skill from one real failure
Di best way to write your own agent skill na to distill am from one real failure. Find one task wey your coding agent do wrong two times, write down the correction wey you type both times, then save that correction as a SKILL.md file wey the agent fit load by itself. Everything after that na mechanics: how the file layout be, and the one line wey decide whether the skill go ever fire.
That order matter. Skill wey you write from imagination dey document problem wey you never get, and e still dey use context for every session. Skill wey you distill from failure wey you watch come with im own test: ask the same thing again, then check whether the agent get am right this time. If the format still new to you, read wetin agent skills be and how agent dey load dem first, then come back and write one.
Start with task wey agent get wrong two times
One time na chance. Two times na pattern, and pattern deserve file.
See one failure wey dey repeat for real servers. You ask agent to add reverse proxy block to nginx. E edit /etc/nginx/conf.d/app.conf, then run sudo systemctl restart nginx. The edit get typo, so nginx refuse to start, and site go down until you fix am:
nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.You correct am for chat. Test the config with sudo nginx -t before you touch the service, then apply am with reload instead of restart. One week later, for another task, the same mistake happen. That second time na the signal.
Write down two things while the failure still dey in front of you: the request wey you type, and the correction wey you give, using the exact words wey you use. Those two lines become the skill. The request show wetin the trigger must match. The correction na the complete content.
Anthropic own authoring guidance put this first. Run the agent on representative tasks without skill, record where e fail, then write the smallest instructions wey fix those failures. The failures na the specification, so if you no fit trace a skill back to one failure, usually na skill wey nobody need. The same filter work for skills wey you install instead of write, and Matt Pocock's 27 published skills divide into the ones wey solo developer for VPS should install and the ones wey only become useful for team.
For worked example of the same distillation, Ponytail turn one repeated failure, where agent rewrite much more than wetin you ask for, into skill wey you fit read from beginning to end before you write your own.
Skill wey get
Skill na directory wey get one required file inside am.
.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│ └── proxy-headers.md
└── scripts/
└── check-and-reload.shSKILL.md dey start with frontmatter block. Na some settings wey dem write for YAML be that. YAML na the same configuration format wey Docker Compose files dey use. E dey between --- markers. After that, instructions dey for markdown. Na the complete skill for the failure wey happen before be this.
---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---
## Rules
Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.
Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.
If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.
For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).That file no reach twenty lines, and e complete skill already. The parts be:
name: e fit reach 64 characters, and na lowercase letters, digits, and hyphens only. E no fit contain the wordsclaudeoranthropic. For personal or project skill, na only display label this one be. The command wey you type dey come from directory name, so this one answer to/nginx-config-changes.description: wetin the skill dey do and when to use am, up to 1,024 characters. This line na the main thing, and the next section talk about nothing else.- The body: instructions wey load only when the skill actually fire.
reference/: extra files wey agent go read when e need dem. Link dem fromSKILL.mdand keep the links one level deep, because file wey another referenced file link to fit only read partly.scripts/: files wey agent go execute instead of read. Na only their output dey use context, so 300 line script cheap.
Skill dey grow reach full layout when the behaviour wey e dey correct stubborn enough to need am. The unlazy skill use that extra space for Depth Tree, gates files, and PLAN.md contract to stop agent from announcing say e don finish while whole branches of the work still dey untouched.
Where you put the directory go decide who fit use the skill.
.claude/skills/<name>/SKILL.mdfor the repository: na this project only, and e go travel go everybody wey clone the repo.~/.claude/skills/<name>/SKILL.md: every project for your machine, and nobody else own.<plugin>/skills/<name>/SKILL.md: dem ship am inside plugin, and e dey available anywhere wey that plugin dey enabled.
Use mkdir -p .claude/skills/nginx-config-changes create one, then write the file. Claude Code dey watch these directories, so if you edit existing skill, e go take effect inside the session wey dey run. If you create top-level skills directory wey no dey when the session start, you need restart, because nothing dey available to watch when the session begin.
The description field na the line for file wey fit bring the biggest effect
When agent start, e dey load the name and description of every skill wey dey available enter its context. E no dey load the bodies. When your request reach, na that one line be the complete basis wey e use decide whether this skill relate, so even perfect body wey dey behind vague description no go ever read.
Write the description for third person. "Tests and reloads nginx safely" dey work. "I can help you with nginx" no dey work, because system prompt go inject the text there, and first person go sound like na the model dey talk about itself.
Put two things inside am: wetin the skill dey do, and the condition wey make am apply. Put the important use case first, because Claude Code dey cut the listing entry for 1,536 characters. Optional when_to_use field dey available for extra trigger phrases and example requests, and e go append to the description under that same cap.
Then use the words wey you go actually type. description: Helps with nginx no match anything, because nobody dey type "helps with". The version above name /etc/nginx, server block, reverse proxy and TLS (transport layer security) certificate path, and na roughly the vocabulary of any request wey suppose trigger am.
This na the test for description. Give that single line to person wey never see the body, together with the request wey you wan type, then ask whether the skill apply. If dem no fit tell, the model no fit tell either.
Make the body short, because e dey stay for context
When dem invoke skill, the rendered content enter the conversation as one message and remain there for the rest of the session. Claude Code no go read the file again for later turns. Every line wey you write na cost wey you go pay for the whole session, no be for one answer only.
Anthropic recommend make you keep SKILL.md below 500 lines and move extra detail go separate files. Compaction show why that number no be arbitrary. When dem summarise the conversation to free context, Claude Code attach the most recent invocation of each skill again, keep only the first 5,000 tokens of each one, then fill combined 25,000 token budget starting from the skill wey dem invoke last. Long skill fit cut off halfway. Several long skills fit push each other out completely.
So write only wetin the model no already know. E know wetin nginx be and wetin reverse proxy dey do. E no know your house rule about reload over restart, and na that rule be the only reason this file dey exist.
If the skill tell the agent to run bundled script, name the path with ${CLAUDE_SKILL_DIR} so e go resolve anywhere dem install the skill, and pre-approve the same command so the run no go stop for permission prompt.
---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---The grant cover the turn wey invoke the skill and e clear when you send your next message, so e no go quietly become permanent permission.
How to prove say skill dey fire
To watch skill load show say agent find am. E no show say answer change. Check both, and check am for fresh session, because session wey you use write skill don already hold everything wey you talk while you dey write am. This leftover context fit hide gaps for the file.
- Start new session with
claudefor the project. - Type request the way you go type am for normal workday, with your own words, without mention skill.
- Watch whether invocation happen. If skill no fire, fix description. Body no be the problem yet.
- Invoke am by hand with
/nginx-config-changesas control. If behaviour correct when you invoke am by hand but wrong when request invoke am, e confirm say na trigger problem, no be instruction problem. - Run the same request with skill switched off, then compare both answers. For
/skillsmenu, highlight skill, pressSpaceto cycle state gooff, thenEnterto save. This one writeskillOverridesentry inside.claude/settings.local.json, and when you pressSpaceagain, e cycle am back toonafter you finish. - Write some requests wey suppose no trigger the skill, and check say e stay quiet for those ones.
To automate this loop, install skill-creator plugin from official marketplace.
/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-officialIf install output talk Run /reload-plugins to activate., run that command. Then ask Claude to evaluate your skill by name. Plugin dey store test cases inside evals/evals.json for skill directory, and e dey run each case for separate subagent. So every run start with clean context. E then write comparison between with-skill and without-skill. Na this be the honest number: how much pass rate improve compared with tokens and time wey skill dey cost.
Skill fit also carry its own proof instead of leaving am for separate eval run. Na this be wetin Old Coder skill dey do when e make agent return evidence report wey you fit rerun by yourself.
Failure mode: skill no dey trigger
You type the request, agent still do the old wrong thing, and no skill line show. Work through these ones in order.
- Description talk wetin the skill dey do but e no ever talk when to use am, so nothing for your request match am.
- Description avoid the words wey you type. If you talk "nginx", description must talk nginx.
disable-model-invocation: truedey set for frontmatter. That one remove description from model context completely, and leave the skill wey you fit invoke only with/name.pathsglob for frontmatter limit activation to matching files, and the file wey you dey work on no match.- Skill dey inside nested
.claude/skills/directory under your starting directory. Dem go load only after agent read or edit file inside that subdirectory, so before then skill no dey available at all.
Failure mode: skill dey trigger all the time
The opposite problem na when description too broad, so skill dey fire for unrelated work. “Use when working on the server” fit match almost any request for server repository. Body go load for tasks wey e no fit help with, and e go remain for context for the rest of the session.
Make description narrow to the condition wey really matter, and name the files or commands wey e covers. Add a paths glob when skill only applies to certain files. For anything wey get side effects, like deploy or commit, set disable-model-invocation: true and invoke am yourself with /name, so agent no go decide by itself say na good time to deploy.
Failure mode: skill dey inside your rules file
Rules file like CLAUDE.md or AGENTS.md dey load for the beginning of every session, and e dey apply to every task. Skill body dey load only when skill fire. Frequency na the whole decision. If fact dey apply to every task for the repository, like the package manager wey you dey use, e belong inside rules file. If na procedure wey dey apply to small part of tasks, like the nginx rule above, e belong inside skill. That one no cost anything on days wey nobody edit nginx.
The real failure na when you put am for both places. The two copies go drift apart, and when agent do the wrong thing, you no fit know which copy e follow. Choose one home for each instruction. If rule already dey exactly one home but agent still dey skip am, na different problem be that. Check the mechanics behind an ignored instruction before you move am into skill and hope say the move go fix am. the boundary between skills, MCP servers and rules files dey explain the harder cases, including when the correct answer na MCP (model context protocol) server wey go give agent new tool instead of new instruction.
Share am once e don prove say e useful
Skill wey fit survive one week of real work dey worth committing. Dem dey review project skills for .claude/skills/ like code, and dem dey come with the repository. So teammate wey clone am go get your correction without any setup step. Moving skill between repositories without copy and paste na separate problem. how to share agent skills across repos cover am.
One portability note. Claude Code dey accept plenty frontmatter fields, but Agent Skills standard allow only six: name, description, license, compatibility, metadata and allowed-tools. If you upload skill to claude.ai, or package am for Skills API, with any other thing for the frontmatter, e go fail completely instead of ignoring the field:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameStay inside these six fields, and the same file go load for Claude Code and for anything else wey dey read the standard. But where the file loads still decide wetin e fit do, because Cowork dey run inside Anthropic sandbox, while Claude Code dey run for your own machine or VPS. So the nginx skill above dey worth carrying go teammate checkout, but e useless for sandbox wey no fit reach the server. Writing the instructions so dem fit work after moving to another model na separate job. writing skills that work with any model cover am.
FAQ
SKILL.md file suppose long reach how much?
Make e no pass 500 lines, and expect say most useful skills go shorter well well. The body dey enter conversation when skill run, and e remain there for the rest of the session. So every line na recurring cost, no be one-time cost. Move long reference material go separate files inside skill directory, then link dem from SKILL.md, one level deep, so agent go read dem only when e need dem. Bundled scripts dey execute instead of read, so na only their output dey cost.
Why my skill no dey trigger at all?
Description na the usual cause, because na only that part of skill dey context when model dey decide. Make sure say e talk when to use the skill, no be only wetin e dey do. Make sure too say e contain the words wey you actually dey type for your requests. If description look correct, check frontmatter for disable-model-invocation: true, wey dey hide the skill completely from model, and check for paths glob wey limit am to files wey you no dey touch. Skill wey dey inside nested .claude/skills/ directory under your starting directory na another possible cause. E go load only after agent read or edit file for that subdirectory.
How I go know whether skill really help?
Compare am with a baseline. Gather some real requests. Run each one for fresh session with the skill available. Then run dem again with the skill switched off from /skills menu, and read both answers side by side. Fresh session matter because the conversation where you write the skill still get your explanations. That one fit make incomplete file look complete. skill-creator plugin dey run this comparison for you and report the pass rate beside the token cost.
I fit use the same SKILL.md with another agent?
Yes, as long as you stay inside the fields wey Agent Skills standard define: name, description, license, compatibility, metadata and allowed-tools. Claude Code dey accept plenty more fields, and e also support body features like shell command injection wey other tools no dey run. If you upload skill wey get field outside the standard, e go fail with clear error wey list the allowed properties. So decide early whether the skill suppose remain for Claude Code or travel go other tools.