Skill Engineering: How to Turn Everything You Do Twice Into a File
文章目录
Researchers ran Claude's smallest model against Claude Opus on 84 real tasks
The small one got a folder of instructions, Opus got nothing, and the small one won: 27.7% against 22.0%, for a model that costs a fifth as much
The folder was a skill, a file that says how the work is done
Most people explain the same task to their agent every week, in a chat that's gone tomorrow
The people getting more out of the same agents explain it once, in a file the agent finds on its own
This article is how to turn everything you do twice into a skill that gives you the same result on every run
The 30-second version
A skill is a folder with one SKILL.md file in it, the format Anthropic shipped in October 2025 and opened up as a standard in December, so the same folder now works in Claude, OpenAI Codex, GitHub Copilot, Cursor and a growing list of other agents
Skill engineering has six parts, and a skill only works when all six are there:
-
Spot - the second time you explain a task, it's a skill you haven't written yet
-
Trigger - the description decides whether the skill ever runs, it's the only part the agent always reads
-
Steps - orders and checks, not explanations, the model already knows what a PDF is
-
Layers - SKILL.md stays short and points to everything else, which loads only when a step needs it
-
Scripts - anything that must come out the same every time is code the agent runs, not a sentence it reads
-
Test - three real tasks before you write a word, and again after every change
Skip trigger and it never fires, skip scripts and it's right most of the time, skip test and nobody knows which time
What skills actually buy you
Before writing one, it helps to see what the research says skills are worth, and when they backfire
Written by people who know the work, they pay
SkillsBench, a benchmark published in February 2026, ran agents on 84 tasks across 11 fields, with and without skills, every task graded by automatic checks, 7,308 runs in total
Skills written by people raised the average pass rate by 16.2 points
The gain depended on the field: +4.5 points in software engineering, where models already know a lot, and +51.9 in healthcare, where they don't
Written by the model alone, they don't
In the same paper, agents were asked to write their own skills before starting the task
On average it didn't help at all, -1.3 points, and the authors' conclusion is that models can't reliably write the procedure they benefit from reading
Focused beats complete
Tasks with 2-3 focused skills gained 18.6 points, while comprehensive documentation loaded as a skill made results 2.9 points worse
A small model with skills beats a big one without
Claude Haiku 4.5 with skills scored 27.7%, Claude Opus 4.5 without them 22.0%
And they can hurt
16 of the 84 tasks got worse with skills, because an agent follows a bad instruction just as faithfully as a good one
The pattern: a skill pays off when a person who knows the work writes it, keeps it short, and tests it
Spot: twice is the signal
The first time you explain a task to an agent, it's a prompt
The second time, it's a skill you haven't written yet
The signs are easy to miss because they feel like normal work:
-
you paste the same instructions you pasted last week
-
you correct the same thing for the second time
-
you keep a note called "how I like it done" and copy from it
-
a teammate asks how you get the agent to do that
Anthropic's own guide to creating skills starts the same way: do the task once with the agent, notice what you kept repeating, then ask it to turn exactly that into a skill
The rule: twice is the signal, once is not, a skill for a one-off task is one more option the agent has to read past
Trigger: the description is the whole discovery system
An agent with 50 skills doesn't read 50 files, it reads 50 descriptions and picks
At startup only each skill's name and description are loaded, about 100 tokens per skill, and the agent matches your request against them
So the description decides whether the skill ever runs:
-
Never fires: "Helps with reports"
-
Fires when it should: "Turns sales call notes into the Monday pipeline update, use when the user shares call notes, transcripts or asks for the pipeline update"
Three rules from Anthropic's guide: say what it does and when to use it, write it in third person, and use the words you'd actually type when you need it
The rule: if the skill never fires, the description is wrong, not the skill
Steps: orders, not explanations
The body of a skill is the procedure, and most people write an essay instead
Anthropic's guide shows the difference on a PDF task: a 50-token version that names the library and shows three lines of code, and a 150-token version that first explains what a PDF is
The model already knows what a PDF is, what it doesn't know is how you want the work done
How tight each step should be depends on how much can go wrong:
-
Open field - many ways are fine, give the goal and the checks: writing, research, reviews
-
Narrow bridge - one wrong move breaks it, give the exact order and say don't improvise: invoices, migrations, anything a client sees
For anything longer than a few steps, a checklist the agent copies and ticks off keeps it from skipping the step that matters
The rule: write what to do and how to check it, never what things are
Layers: SKILL.md is the table of contents
A skill can hold far more than the agent ever reads at once, because it loads in three layers:
-
Description - always loaded, about 100 tokens
-
SKILL.md - loaded when the skill fires, under 500 lines, under 5K tokens
-
Everything else - reference files, examples, templates, read only when a step needs them, zero tokens until then
That's what lets one agent carry dozens of skills without drowning its context
Two rules from the docs keep it working: link every extra file straight from SKILL.md, one level deep, because files linked from other files get skimmed, and put a table of contents at the top of any reference file longer than 100 lines
The rule: SKILL.md is the table of contents, not the textbook
Scripts: if it must come out the same, it's code
Some steps have to come out identical every single time: totals, dates, formatting, file conversions, checks
Those don't belong in instructions, they belong in a script the skill tells the agent to run
When an agent runs a script from a skill, the code never enters the context, only the output does, a line like "validation passed" or the exact error
Anthropic lists why that beats letting the agent write the same code on the fly: it's more reliable, it saves tokens, it saves time, and it's the same on every run
Two details make scripts work: say clearly whether the agent should run the file or read it, and write error messages specific enough that the agent can fix the problem on its own
The rule: if a mistake would be embarrassing, it's a script, not a sentence
Test: three tasks before you write a word
Anthropic's guide says to build the tests before writing the skill, not after
-
Run the task without a skill and write down where it goes wrong
-
Pick three real tasks that hit those gaps, with answers you already know are right
-
Score the agent on them without the skill, that's the baseline
-
Write just enough skill to close the gaps
-
Run the three tasks again and compare
After that, every failure in real use becomes one new line in the skill and one new test
The guide's other trick: one agent helps you write the skill, and a fresh one that never saw that chat uses it, because the one that wrote it already knows what you meant
The rule: a skill without three tests is a guess written in markdown
A worked example: the Monday pipeline update
Here's the same idea on a real-looking task
Say every Monday you turn last week's sales calls into a pipeline update: each deal's stage, the totals, the next steps
The prompt version: you paste the same 400 words of instructions, the agent writes the update, you spend 25 minutes fixing it, and about one week in three the total is wrong
The skill version:
-
Spot: you've pasted those 400 words nine Mondays in a row
-
Trigger: "Turns sales call notes into the Monday pipeline update, use when the user shares call notes or asks for the pipeline update"
-
Steps: 9 numbered steps and a checklist, 52 lines in total
-
Layers: what each deal stage means lives in reference/stages.md, read only when a deal changes stage
-
Scripts: totals.py adds up the deal values, the agent never does the math
-
Test: three past Mondays with known right answers, run after every change
Fixing time goes from 25 minutes to 4, wrong totals from 3 of the last 10 weeks to 0 of the next 10, and you never paste the 400 words again, same agent, same model
The file: SKILL.md
Give it to any agent that reads skills, the brackets are the only part you change:
name: [weekly-pipeline-update] description: [Turns sales call notes into the Monday pipeline update], use when [the user shares call notes or asks for the pipeline update] GOAL: [one line, what done looks like] STEPS: [numbered, one order per line, no explanations] CHECKLIST: copy these steps into your reply and tick each one off as you go RULES: [the 3-5 things you've corrected more than once, one line each] RUN, DON'T WRITE: scripts/[totals.py] for [anything that must come out the same every time] READ ONLY WHEN NEEDED: [reference/stages.md] when [a deal changes stage] EXAMPLE: [one real input and the output you'd accept] BEFORE YOU SAY DONE: [the 3 things a person would check first]
The RULES line is where every future correction goes, one line each, that's how the skill gets better without getting longer
Which part your skill is missing
When a skill isn't pulling its weight, the symptom tells you which part is broken:
-
you have 30 skills and use 4 → spot, the rest were one-offs
-
it never fires when you need it → trigger, the description doesn't use your words
-
it runs, but the result is different every time → steps, it explains instead of ordering
-
it reads 2,000 lines to do one small thing → layers, everything is crammed into SKILL.md
-
the total is wrong once a month → scripts, the agent is doing the math
-
it worked in March and nobody noticed when it stopped → test, there's nothing to rerun
Six symptoms, six parts, and a bigger model fixes none of them
The mistakes that make skills useless
Asking the agent to write the skill and walking away
Self-written skills averaged -1.3 points in SkillsBench, the agent can draft it, but the procedure has to come from you
Pasting your whole wiki into one skill
Comprehensive documentation made results worse, a skill is the 50 lines that matter, not the 5,000 that exist
One giant skill for your whole job
The description can't say when to use it if the answer is always, split it by task
Installing skills from strangers without reading them
A skill can tell the agent to run code or send data somewhere, Anthropic's own docs say to treat it like installing software and to read every file first
Writing it once and never touching it
The tool changes, the client changes, the price changes, and the skill keeps doing it the old way with full confidence
Explaining instead of instructing
Every paragraph about what something is costs tokens and buys nothing, the model already knows
Where to start tonight
-
Scroll back through last week's chats and find the instructions you pasted more than once
-
Pick the one that costs you the most time
-
Write the description first: what it does and when to use it, in the words you'd actually type
-
Copy the SKILL.md above, fill the brackets, keep it to one screen
-
Run it on three past tasks where you already know the right answer
Then count how many times you paste the same instructions next week
P.S: The best prompt you'll ever write is the one you only have to write once
If you read this far
→ Bookmark this, so the 6 parts, the SKILL.md template and the six broken skills are right there whenever you notice you're pasting the same instructions again
→ Join my Telegram channel
→ Follow @distortgeekin for a new AI agent breakdown every day
沿着这个主题继续读
从一篇文章,找到相关的教程、经验和阅读路径。







