AI Guides › Workbench
By Nigel Guy · 7 min read
Most people who keep re-explaining themselves to Claude fix it with a bigger prompt. They paste the same house-style paragraph at the top of every chat, and it works until they forget to paste it. The opposite mistake is the "master skill": one enormous instruction file for everything, which Claude then follows loosely because nothing in it is specific.
The rule: write one skill per repeated job, keep each one narrow, and test it on a real task before you trust it.
A note on sources. The article behind this topic describes nine specific skills running an AI team. I could not check those nine, so this guide does not describe or endorse them. What follows is the part that can be verified: what a Claude skill is, where it lives, and how to build one that earns its place.
A skill is a folder with a SKILL.md file. The file starts with YAML frontmatter (a name and a description) followed by plain Markdown instructions. Claude keeps only the name and description in view all the time. It reads the full file when a task matches, and reads any extra files in the folder only if it needs them. That is why many skills can coexist without swamping a conversation.
| Route | What it does | Cost at time of writing | Best for | Catch |
|---|---|---|---|---|
| Claude (claude.ai) custom skill | Upload a zipped skill folder; Claude applies it in chats and file work | Skills are listed on Free, Pro, Max, Team and Enterprise, but need code execution switched on. Pro is $20 a month ($17 on annual billing), about £16 at time of writing; check the £ price at checkout | Writing, document and analysis routines you run in the app | Anthropic's help page says only install skills from sources you trust |
| Claude Code personal skill | A folder at ~/.claude/skills/<name>/SKILL.md, available in every project on that machine |
Claude Code needs a paid Claude plan or API usage; Max starts from $100 a month, about £80 at time of writing (check at checkout) | Your own habits across all repositories | Lives on one machine unless you sync the folder |
| Claude Code project skill | A folder at .claude/skills/<name>/SKILL.md inside a repository |
As above | Rules a whole team should share, committed with the code | Anyone with the repo gets the rule, so review changes like code |
Switch it on. On Free, Pro and Max, go to Settings, then Capabilities, and enable "Code execution and file creation". On Team and Enterprise an owner enables both that and Skills under organisation settings (Plugins & skills, Policy tab).
Upload. Put your folder inside a ZIP, with the folder as the top level. Go to Customize, then Skills, click "+", then "+ Create skill", choose "Upload a skill" and select the ZIP. Toggle it on from the same Skills list.
Draft it with Claude. Anthropic's own guidance says Claude already understands the format, so you can ask it to write the file after you have done a task by hand. Use this once the task has gone well:
You are helping me turn a task we just completed into a reusable Claude skill.
Context: the task was [TASK_IN_ONE_LINE]. The rules I corrected or repeated during it were [RULES_I_KEPT_REPEATING]. Good output looks like [WHAT_GOOD_LOOKS_LIKE].
Write a SKILL.md with:
1. YAML frontmatter: a lowercase-hyphenated name, and a description in the third person that says what the skill does and when to use it.
2. A short numbered procedure.
3. An output format section.
4. A "never" list drawn only from what I told you.
Rules: do not explain things Claude already knows. Keep it under 80 lines. If you need an input I have not given you, ask me before writing. Before you answer, check that every line comes from this conversation and flag anything you inferred.
Fill in the three bracketed items from the conversation you just had.
Beginner trap. Anthropic's help page for custom skills names the file skill.md and gives the description a 200-character limit, while the developer documentation says SKILL.md and allows 1,024 characters. I could not reconcile the two. Use SKILL.md, keep your description short, and if the upload is rejected, check the error message first.
Create the folder ~/.claude/skills/<skill-name>/ and put SKILL.md inside. The folder name becomes the slash command, so weekly-report/ becomes /weekly-report, unless you set name in the frontmatter. Two settings matter most:
disable-model-invocation: true stops Claude running the skill on its own, so it only fires when you type the command. Use it for anything with side effects, such as sending, deploying or deleting.allowed-tools pre-approves specific tools for that one turn only.Per the Claude Code documentation, the description and when_to_use text are truncated at 1,536 characters combined, and SKILL.md should stay under 500 lines, with long reference material in separate files.
The same structure sits at .claude/skills/<skill-name>/SKILL.md inside a repository, so it loads for sessions in that project. Use it for house rules that should travel with the code, and keep personal preferences out of it.
Anthropic recommends building evaluations first: run Claude on representative tasks without the skill, note exactly where it fails, then write the minimum instructions that fix those failures. Use this prompt in a fresh chat:
You are a sceptical reviewer of a Claude skill.
Skill under review: [PASTE_SKILL_MD]
Three real tasks it should handle: [TASK_1], [TASK_2], [TASK_3].
For each task, say whether the description would make Claude choose this skill, then predict where the instructions are ambiguous or leave out a rule I would have to correct by hand. Output a table: task, would it trigger (yes/no/unclear), likely failure, suggested one-line fix.
Do not rewrite the whole skill. If a task is too vague to judge, ask me. Before you answer, check each failure you list is supported by a specific line, or the absence of one, in the skill.
Then run the real tasks for yourself. A prediction is not a test.
Start in the app if your work is writing and documents. Use Claude Code if your work is files and repositories. Use a project skill only when a rule belongs to the team rather than to you. If you are unsure, build the app version first; it is the quickest to throw away.
Pick the job by counting repeats. If you have corrected Claude on the same point three times, that point is a skill. A starter shortlist of slots worth filling: a house voice, a weekly report format, a meeting-notes format, a review checklist, a client-email tone. That is a prompt for your own list, not a claim about anyone else's nine.
helper. Use a name that states the job, and note the name cannot contain "anthropic" or "claude" in the developer documentation's rules.