Let's Talk
← All writingPublished October 20, 2026

How to write good Claude skills

ClaudeSkillsAI agents
On this page

A good Claude skill does one job, has a description written in the words your team uses when they ask for that job, and holds the steps your best person really follows, with real examples beside them. Test it on last month's real work against what that person sent, and fix the steps wherever the two differ.

The file takes minutes to write. What makes it worth having is the knowledge in it, and that part comes from your team rather than from Claude.

What a skill is, and when Claude uses one#

A skill is a folder of instructions, and sometimes scripts and files, that Claude loads when a task calls for it. At the start of a conversation Claude reads only the name and description of each skill you have, about a hundred tokens apiece according to the Agent Skills specification. It reads the full instructions only when a task matches, and opens the extra files only when the instructions point to them. So you can keep many installed, and only the one a task needs gets read in full.

That's what sets a skill apart from instructions you paste into every chat, which are always on. Anthropic released the format as an open standard, Agent Skills, and the same folder now works in ChatGPT and Codex, GitHub Copilot, VS Code and Cursor as well as in Claude.

Pick one job#

The skills that work are narrow. Anthropic's own advice is to keep each one to a single workflow, since several focused skills work together better than one large one.

Pick a job your team repeats every week, that comes out the same way each time, and where a good result depends on knowing how your business does things. The client report, the proposal, the contract check and the month-end spreadsheet are the usual first ones, and so is writing in someone's voice, which How to train AI on your writing style walks through.

Then sit with whoever does that job best and write down the steps the way they really do it, including what they check before anything goes out. Most of that has never been written down anywhere, and it's what makes the skill worth having.

Write the skill file#

Here's a complete skill for a weekly client report.

---
name: weekly-client-report
description: Writes the weekly client report from the project tracker export. Use when someone asks for a client update, a weekly report or a status email for a client.
---

# Weekly client report

1. Read the tracker export the user attaches. If there isn't one, ask for it.
2. Group the work under Done, In progress and Blocked.
3. Write one plain sentence per item about what changed for the client.
4. Put anything waiting on the client at the top, with the date it's needed by.
5. Follow the layout in template.md and the tone of the reports in examples.md.
6. Keep it under 300 words, and leave out internal costs.

The description matters most, because it's what Claude reads to decide whether to use the skill at all. Say what the skill does and when to use it, in the words your team uses when they ask for that job. If people say "client update" in one place and "status email" in another, both belong in it. The open standard allows 1,024 characters and the Claude app takes 200, so a description under 200 works everywhere.

The name is lowercase letters, numbers and hyphens, up to 64 characters, and it matches the name of the folder.

Under the description go the steps, in order, written as plainly as you'd explain them to a new hire. Anthropic suggests keeping the file under 500 lines and moving long reference material into separate files.

Add real examples#

Real examples of good work teach Claude more than any description of good work. Put two or three past reports in examples.md and the layout in template.md, and mention both in the steps, so Claude knows what each file holds and when to open it.

weekly-client-report/
├── SKILL.md
├── examples.md
├── template.md
└── scripts/
    └── totals.py

Scripts are for anything that has to come out the same every time, such as adding up hours or checking a total. Start with plain instructions and add a script only when the instructions aren't enough.

Can Claude write the skill for you?#

Partly, since Anthropic publishes skill-creator, a skill that helps Claude draft, test and improve other skills, and in Cowork for Mac you can record yourself doing a task for up to about ten minutes and Claude proposes a skill from what it saw.

What Claude can't supply is the knowledge. SkillsBench, a study of how well skills work across 18 combinations of agents and models, found that curated skills raised the share of tasks finished from 33.9% to 50.5%. Skills the agent wrote for itself before starting did worse than no skill at all, on all three combinations that tried it. So let Claude do the typing, from your steps and your examples.

Test it on real work#

Ask for the job the way people on your team really ask for it, in a few different ways, and check that Claude loads the skill, which the Claude app shows in Claude's thinking. If it doesn't load, the fix is usually the description, so add the words people actually used.

Then run it on last month's real inputs and put the result next to what your best person sent that week. Wherever the two differ, a step is missing or vague, so fix the step rather than the output. Test again after every change that matters.

Keep it current#

A skill goes stale the way a written process does, quietly, while the job changes around it. Give each skill an owner, the person who does the job best, so it changes when the job does, and rerun the same test whenever it does.

Add it to Claude, Claude Code or Cowork#

In the Claude app, skills work on every plan, Free included, once code execution is switched on in Settings, under Capabilities. Zip the folder so the ZIP holds the skill folder itself, then open Customize, then Skills, click the plus button and choose Upload a skill.

In Claude Code, put the folder in ~/.claude/skills/ to use it in every project, or in .claude/skills/ inside a repository to use it there. Claude picks it up when a task matches, and you can also run it yourself by typing /weekly-client-report.

In Cowork, skills usually arrive inside a plugin, a package of skills, connectors and helper agents for one role, on any paid plan. Open Customize, then Plugins, where you can add one from Discover or upload your own. A plugin's skills work in chat, in Cowork and in Claude Code alike.

Share it with your team#

On Team and Enterprise plans an owner turns on sharing under Organization settings, in Plugins and skills, and then anyone can share a skill from its menu in Customize. Shared skills are view-only, and sharing with whole groups needs Enterprise. In Claude Code, commit the .claude/skills folder to the repository, and everyone who clones it has the skill. Because the format is an open standard, the same folder works for the people on your team who use ChatGPT or Copilot.

That's how the triage prompt I wrote for a New York Times bestselling author's vault works. It shows her where each new note would go and moves nothing until she approves, and every answer she gives it becomes a rule it follows from then on, so what it knows comes from her. If you'd rather have your team's jobs turned into skills, send me the job your team repeats.

Sources#