好文集ChatGPT Plus¥119

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

  1. Run the task without a skill and write down where it goes wrong

  2. Pick three real tasks that hit those gaps, with answers you already know are right

  3. Score the agent on them without the skill, that's the baseline

  4. Write just enough skill to close the gaps

  5. 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

  1. Scroll back through last week's chats and find the instructions you pasted more than once

  2. Pick the one that costs you the most time

  3. Write the description first: what it does and when to use it, in the words you'd actually type

  4. Copy the SKILL.md above, fill the brackets, keep it to one screen

  5. 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

全文完
查看原文

沿着这个主题继续读

从一篇文章,找到相关的教程、经验和阅读路径。

AI SkillsAI Skills 使用、编写与工作流实践,按开发、表格和知识整理任务选技能。