Matthew Boston

If you can't one-shot your feature, it's a SKILL.md issue

March 14, 2026

Key takeaway: When an agent misses a feature, fix the context it reads by updating SKILL.md, instead of prompting harder.

If your agent can’t one-shot a feature, it’s usually missing context. Write down what it lacked in a SKILL.md file and try again.

Engineers have always tuned their tools. We tweak terminals, write shell aliases, and build custom linters to cut the friction between intent and execution. A SKILL.md is the next layer. Instead of a vim macro, you’re writing down how your codebase approaches a type of task, so the agent can match it.

It’s context that persists across sessions: the patterns, conventions, and domain knowledge that separate generic code from code that fits your project. If you keep correcting the same mistake, what’s missing is context. Typing harder won’t help. Bad context in, bad code out.

My loop:

  1. Let the agent take its best shot.
  2. Find where it went wrong. Missing conventions, wrong patterns, or a gap in domain knowledge.
  3. Write that down in a SKILL.md or CLAUDE.md so it’s there next time.
  4. Try again. If it’s still off, repeat.

Over time those files hold your project’s tribal knowledge in a form both people and agents can use. Each improvement pays off on every later feature. The agents get better because the context does, even when the model stays the same. A published SKILL.md also means anyone can spin up a copy of your expertise.