SKILL 33 / PKM · DEEP DIVE

Growing a Skill From Repetition

Notice what you re-explain every time — the shortest path from one real task to one skill

2026-10-04 · BigCat

Last issue concluded that the output layer is something you write yourself. This one is about how: don't sit down and write a skill from a blank page. Do the task once, then have the model extract the places where you corrected it. Below are 9 real items you can install or read: official docs, an official plugin, built-in commands, and one community methodology.

Same series → Skill 32 Personal Productivity Roundup · Skill 7 Writing Evals for Skills · Skill 27 Hooks and Deterministic Automation

// WHY THIS MATTERS

The Claude Code docs give one test for when to build a skill: Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat. The claude.com guide phrases it differently: when you find yourself correcting Claude with the same instructions. Both point at the same signal: repeated explanation is the raw material of a skill. That leaves one question: how to pull it out of the conversation, instead of writing yet another generic "best practices" file.

// 01

What it removes · install · the first prompt that works

Claim: the shortest path is three steps. Finish the task as usual, say "turn this into a skill", then check it against the next real task.

It removes re-explaining everything in every new session: table names and metric definitions, your report format, rules like "exclude test accounts for this kind of request". The main tool is the official skill-creator:

# Claude Code: the skill-creator plugin from the official marketplace
/plugin install skill-creator@claude-plugins-official
# If it reports "Marketplace not found", add the official marketplace and retry
/plugin marketplace add anthropics/claude-plugins-official

# First prompt: in the same session where you just finished the work
Turn the workflow we just used into a skill with skill-creator.
Keep the places where I corrected you along the way.

Why the same session? Because the first step of skill-creator, Capture Intent, says that if the current conversation already holds a workflow the user wants to capture (say, the user types turn this into a skill), it should extract answers from the conversation history first: the tools used, the order of steps, the corrections the user made, the input/output formats it saw. Then it asks you to fill the gaps and confirm. Open a new window and all of that raw material is gone.

Where the file goes: ~/.claude/skills/<name>/SKILL.md is personal (every project on this machine); .claude/skills/<name>/SKILL.md is per project (commit it to share with your team). After that, Claude calls it when a request matches the description, or you type /<name>.

When not to bother: you will only do this once. In the words of the official claude.com guide: for a one-off task, just describe what you want in the conversation.
// 02

Mechanism: why "do it once, then extract" beats "just write it"

Claim: a skill generated from nothing holds only what the model already knows. One extracted from a real task holds what it doesn't.

agentskills.io, the official site for the open Agent Skills specification, names this trap at the top of "Best practices for skill creators": ask an LLM to write a skill from its training knowledge alone, and you get filler like "handle errors appropriately" or "follow best practices for authentication". The first fix it offers is called Extract from a hands-on task, and it tells you to watch four things:

Anthropic's "Skill authoring best practices" writes the same idea as seven steps with Claude A and Claude B. First, finish the task with Claude A and no skill, and notice what information you repeatedly provide. Then find the reusable pattern, have A write the skill, cut needless explanations, and tidy the structure. Next, open a fresh instance B with the skill loaded, give it similar tasks, watch what it misses, and take that back to A. The docs also point out that you don't need a special "writing skills" skill; ask Claude to write one and it follows the format.

On the community side, the strongest take is writing-skills inside obra/superpowers, which treats this as TDD: run a baseline without the skill and record the agent's exact excuses (RED), write the smallest skill that targets those violations (GREEN), then close the loopholes (REFACTOR). Its key line: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

Do it once (Claude A) Extract Check (Claude B · new session) ────────────────────── ────────────────────── ────────────────────────────── real task + corrections → steps / corrections / → the next similar real task formats / context what it missed → back to A → SKILL.md
// 03

Real usage and limits: which repetition should become a skill

Claim: repetition is necessary, not sufficient. Three kinds of repetition have better homes.

How to spot repetition

Three kinds of repetition that shouldn't become a skill

Two switches to set correctly

For workflows with side effects (deploys, commits), add disable-model-invocation: true to the frontmatter so only you can trigger them with /name. For anything that needs live data, use an inline command such as !`git diff HEAD`. It runs before Claude sees the skill and injects the live output.

// 04

Costs and alternatives

Claim: more skills is not better. Once one grows, you still owe it a test.

① Overfitting to that one task

skill-creator warns about this itself. You iterate on a few examples because it is fast, but a skill that works only on those examples is useless. The goal is a skill that can be used a million times, not one stuffed with "fiddly overfitty changes, or oppressively constrictive MUSTs". After extraction, test it on a real task it has never seen.

② The listing budget squeezes out rarely used skills

From the official docs: skill names and descriptions sit in a standing listing whose budget is 1% of the model's context window. When it overflows, descriptions are dropped starting with the skills you invoke least, and a skill without its description is hard to trigger automatically. A single description plus when_to_use is also cut off at 1,536 characters. A loaded body stays in context, so every line is a recurring token cost.

③ Recipes go stale

A recorded workflow is only true for the environment on the day you recorded it. The docs tell you to run /run-skill-generator again when the build or launch changes. A personal skill has no such reminder; when it goes stale it just quietly does the wrong thing.

Alternatives, cheapest first: paste it (one-off) → one line in CLAUDE.md (a fact it should always know) → a hook (a rule that must always hold) → a skill (a procedure you keep pasting) → a plugin (several skills to install and share together). First ask whether it can move one step left.
Sources: Claude Code · Extend Claude with skills (1% listing budget, 1,536-character cutoff, body stays in context, hook troubleshooting) · skill-creator SKILL.md ("a million times") (all as of each page, 2026-10)

// One-page buying card

Start with these three: ① /plugin install skill-creator@claude-plugins-official. When the work is done, say "turn this into a skill" in the same session; it extracts the steps and your corrections from the history, then runs with-skill vs. without-skill comparisons. ② Read the Claude A / Claude B seven steps in the official "Skill authoring best practices" and follow its rhythm for testing. ③ Read writing-skills in obra/superpowers. You don't need the whole Superpowers suite; just copy its RED step of watching the agent fail first.

Add as needed: /run-skill-generator (when your project's launch steps are complex) · /insights (many local sessions, and you want to find where you keep getting stuck) · template/ in anthropics/skills (a minimal skeleton when writing by hand) · skills-ref validate (check frontmatter before sharing).

Don't: ask the model to "write a skill for X" without real context · try to extract in a new session (the raw material is gone) · turn always-true facts into a skill · keep must-hold rules only in a skill.

// Glossary

Capture Intent
The first step of skill-creator: pull tools, steps, corrections and input/output formats out of the current conversation, then ask you about the gaps.
Claude A / Claude B
The official iteration method: A helps you write the skill; B is a fresh instance with the skill loaded that exposes gaps on real tasks.
Baseline
What the model does without the skill. Without one, you can't tell what the skill actually changed.
disable-model-invocation
A frontmatter switch. Set to true, Claude won't call the skill on its own; only you can, with /name.
Listing budget
The standing list of all skill names and descriptions, capped at 1% of the context window; on overflow, descriptions of the least used skills go first.

// Three things that don't add up

The docs say a description should cover "what it does and when to use it"; writing-skills says "only when to use it". Which is right?
They guard against different failures. The docs care about getting picked: Claude chooses among a hundred-plus skills, so the description needs the key terms. writing-skills guards against getting picked and then not reading the body. It records a test where a description that summarized the workflow ("code review between tasks") led the agent to do one review and skip the two-stage review in the body's flowchart; once the description only stated the trigger, the agent followed the body. My compromise: state when to use it and the key terms, but don't put a summary of the steps in there. Leave the procedure to the body.
Is there a standard number of repeats before something deserves a skill?
The official docs give no count, only shapes: instructions, checklists or multi-step procedures you keep pasting, or correcting Claude with the same words. My own line is the third time I re-explain the same thing. That is a personal habit, not an official rule. A better test is cost: if one line in CLAUDE.md solves it, skip the skill; if getting it wrong causes incidents, use a hook.
If Claude will write a skill when asked, why do the task first?
Because what it writes is what it already knows. The agentskills.io test is to ask of each line, "Would the agent get this wrong without this instruction?" and to cut it if not. Most lines of a skill written from nothing fail that test; what survives extraction from a real task is exactly the set of places where you corrected it. That is also why extraction belongs in the same session: in a new window, the model can only fall back on general knowledge.

// Further reading