Agent skills: start small and write your own

AI agents like Claude Code, Codex, Cursor and Gemini CLI can all load skills, and public packs now ship hundreds of them at a time. This site's repo has six skills. Two of them came out of my own work on it.

My advice is to install fewer skills than you think you need, and to write the first one yourself.

A skill is a folder with a SKILL.md file in it. The file opens with a name and a description, and the rest is plain Markdown. The folder can also hold reference notes or scripts, which the agent opens only when it needs them.

At the start of a session, the agent reads only the name and description of each skill. It loads the full instructions when your request matches a description, or when you type the skill's name, like /ux-copywriting. The description decides whether the agent picks a skill on its own, so name the task in it, and the words you'd use to ask for it.

CLAUDE.md and AGENTS.md files are different. They load in full at the start of every session, so keep them for facts the agent always needs.

If you paste the same instructions into chat every week, or make the same correction in every session, that's a skill. Two kinds of knowledge are worth writing down.

What the agent can't know. Your taste and your house rules. The model behind the agent has read plenty of React tutorials, but none of your case studies. In SkillsBench, a study of 87 tasks, skills written by people raised the average pass rate from about a third to a half.

A task with one right way to do it. Some jobs need an exact order and exact settings. My web-video skill holds the encoder settings for the showreel, and the test results that ruled out a WebM version.

Skills can also make results worse. In the same study, 13 of the 87 tasks went down with a skill.

Too many skills. Every installed skill puts its description in front of the agent with every message, whether it runs or not. Similar descriptions can compete, so the agent picks the wrong skill, or none. In SkillsBench, which gave each task its own skills, tasks given one to three skills gained 18 to 19 percentage points. Tasks with four or more gained 10.

Too much text. Skills written like full documentation added under one point. Compact and mid-length skills did best. Public skills vary a lot here. Matt Pocock's grilling skill runs to about 300 words. gstack's office-hours has about 13,000, ten times the length of this post.

Many popular skills were written for older models, which needed each step listed and key rules in capitals. Newer models work out what you want from a short instruction. Anthropic's guide for Claude Fable 5 says skills written for older models are often too strict for it and can make the output worse. Anthropic's prompting guide adds that rules in capitals, like CRITICAL or MUST, can make newer models reach for a tool they don't need.

Anthropic also suggests testing a skill on every model you use, because a small model may need more detail than a large one. No pack fits everyone. The right one depends on your projects and your model, and it changes with each new model. A short skill of your own is easier to keep current. When the model changes, test each rule and delete what it no longer needs.

1. Do the task without a skill. Note what you explain twice, and where the agent goes wrong.
2. At the end of the session, ask the agent to turn those notes into a skill, with the prompt below.
3. Cut anything the agent already does well.
4. When the skill misses something, add one rule and its reason.

Write it from a real session. In SkillsBench, agents that wrote their own skills before a task, with no input from a person, did worse than agents with none. The value is in what you bring, like a correction or an edge case you've hit. That's why the prompt below starts from your corrections.

My ux-copywriting skill started this way. While I edited the Ford Spot and Taiko case studies with Claude Code, I kept making the same fixes. Cut the em dashes. Cut words like "leverage". Say each fact once. Never invent a number. I turned those fixes into a skill. Two days later, the captions for the GameStop case study came out as lists of what was on screen, so I added a section on captions. It's 266 lines now, longer than I'd tell anyone to start with.

Read packs to see how other people build a skill, then copy the one or two you need. A whole pack brings its author's way of working, often with hooks, which are scripts that run on their own at set moments. I've used the first three. From lightest to heaviest:

• mattpocock/skills. Small skills that call each other. Start with grill-me, which has the agent question you about a plan before it builds.
• addyosmani/agent-skills. 25 skills from spec to ship, each with the same layout and a closing checklist.
• ECC. Over 300 skills, plus agents, hooks and rules. Its README says to start with the one workflow you need.
• gstack. Garry Tan's long skills that act as roles, like a CEO who reviews your plan. Its setup adds hooks to Claude Code.

Run it before you close the session.

Look back over this session. List the instructions I gave you more than once, the corrections I made, and the questions you had to ask me.

Turn the ones that will come up again into a skill at .claude/skills/[skill-name]/SKILL.md.
- Write the description first. Say what the skill does, and the words I use when I need it.
- Keep the body under 40 lines. Leave out anything you already do well without being told.
- Give the reason for each rule, so a later session can handle a case the rule doesn't cover.
- Use plain instructions. No rules in capitals.

Show me the draft before you save it.

This is the captions part of my ux-copywriting skill, cut down to its rules. Save it as .claude/skills/case-study-captions/SKILL.md, then swap in your own reader and your own rules.

---
name: case-study-captions
description: Writes and edits captions for case-study screenshots. Use when adding a screenshot to a case study, or when asked to caption an image or tighten a caption.
---

# Case-study captions

The reader is a hiring manager who skims. The screenshot already
shows what is on screen, so the caption says what it lets someone do.

- One sentence, two at most.
- Name what the person can do. "Turning on a new network takes one
  button" beats "Network toggle, NFT gallery and balance list."
- Use "I" for what I did, and name the team for what they did.
- Never invent a number. If the source has none, ask me.
- Alt text is a different job. It describes the image literally,
  so never reuse a caption as alt text.

The next time you correct the agent about the same thing twice, write it down as a skill, in a few lines. Or see the case studies the copy skill helped write.