Before You Write Agent Skills, Look at How It Fails
The biggest pitfall when writing Agent Skills is writing them too early. Let the agent run first, record its failures, and turn those failures into the skeleton of the skill. Akshay’s 15 tips, plus real feedback from readers.
The most common problem when writing Agent Skills is writing them too early.
A Skill is a reusable workflow in AI coding tools like Claude Code, and the agent decides whether to load it based on its description. You spend hours making a beautifully formatted Markdown file that describes the perfect workflow, the agent runs it, and it still makes the same mistakes. The problem isn’t in the body; it’s earlier.
Akshay listed 15 tips on Twitter, and the core is just one: let the agent fail first, then start writing.
The failure list is the skill
Run the agent on 3 real tasks without the skill and write down every place it gets wrong. That list is your skill; everything else is filler. One reader added: failure before code is the only honest spec.
The description is a trigger, not a summary
Before the agent decides to load a skill, it can only see the name and description. If the description is vague, none of the content written after it will be read.
Put all of 'when to use this' into the description; don’t summarize the workflow in the description. The body is only read after the agent has made the decision to load. And a one-line summary will be executed directly as an instruction, rather than as the full process you wrote.
Use the words users will actually type: file names, error messages, tool names, lazy versions of requests. Don’t use internal jargon.
Stop explaining things the model already knows
Claude knows what a PDF is. Every line either changes behavior or gets deleted.
All-caps ALWAYS and NEVER are red flags. Only rules with reasons can cover scenarios you haven’t thought of. Anthropic’s Claude Code team calls these gotchas. Their best skill started with a few lines plus one pitfall, and every time Claude tripped, it grew by one.
What isn’t a skill
Things that must happen every time are hooks. Things every agent task needs go in CLAUDE.md or AGENTS.md. A skill is the middle ground. One reader cleaned up their setup and cut it from 60 skills down to just 2—most skills shouldn’t exist at all.
Test triggers like you’d test a classifier
Twenty prompts: half should trigger, half shouldn’t. Make negative samples close matches, not joke cases like 'What’s the weather today?'
Run the same set of prompts without the skill, in a clean context, across multiple rounds. Agents aren’t deterministic; one green light proves nothing.
Read the logs; don’t just look at the output. File-open order, references that are never touched, the same file reread every round—that’s where the real bugs hide. One reader said tip 12 saves the most time: first figure out which stage broke. Not loaded? Fix the description. Loaded but doing the wrong thing? Fix the body. They used to spend hours editing the body when the skill had never even loaded.
Use two agents to write a skill: one helps you write it, and one that only loads the skill and actually uses it. The writer already knows your intent and can’t see the gap.
Change one thing at a time
Keep a held-out test set; otherwise you’re just overfitting to your five favorite prompts. Each real failure becomes a test and a gotcha, and you rerun everything after a model update. A skill that worked last month may break this week; sometimes a new model doesn’t need it at all.
Akshay’s pro tip: copy this post into Claude Code or Codex, point it at your skills folder, and have it audit every existing skill you have against these 15 points.
Then keep iterating.
To learn the full configuration of the .claude folder, including CLAUDE.md, hooks, agents, and permissions, see Akshay’s article: Anatomy of the .claude/ folder
发布时间: 2026-11-21 21:34