Skip to content

Knowledge base

Authoring skills

How to write a skill that fires and works, evaluate it before shipping, and whether an agent can tune one unattended, for teams extending Claude Code.

Written by

Updated:

Tools 4

Our position. We give every skill one owner, the role whose work it describes, and a change goes in as a commit through the same checks as code (opens in a new tab). A rule inside a skill stays a polite request (opens in a new tab) that the agent may stop following as its context fills.

The agent picks a skill by its description alone, then reads SKILL.md and runs the bundled scripts. That makes the description the trigger and the shared context window the budget, and most skill authoring advice protects one or the other.

When is a skill the right place?

When a procedure is needed sometimes, not on every turn. Rules that must hold everywhere belong in the instruction file. A step that must happen with no exception belongs in a hook. A repeatable way of doing a task, such as writing a release note or reviewing a migration, fits a skill, because it costs context only when it is used (Anthropic - Extend Claude with skills (opens in a new tab)).

What matters most when writing a skill?

A good skill is selected reliably, closes a gap you observed, and stays small enough to maintain.

  • Write descriptions for selection and keep the main instructions focused on the workflow that changes behavior.
  • Find the gaps first by running the task without the skill, then add only the guidance needed to close them.
  • Keep the active skill set small enough to test, prune, and maintain as models change.

How do you write a skill that fires and works?

Write the description for selection and keep the body to the workflow that changes behavior.

A skill only helps if the agent both selects it and can act on it, and Anthropic’s authoring guidance is mostly about protecting the shared context window. Only a skill’s name and description preload at startup; SKILL.md is read when the skill becomes relevant, and bundled reference files and scripts load or execute only when needed, so a large skill carries no context cost until it fires (Anthropic - Skill authoring best practices (opens in a new tab)). The rules that follow: keep SKILL.md under 500 lines and split overflow into files linked one level deep from SKILL.md, because Claude previews deeply nested files with partial reads and misses content; write the description in third person with both what the skill does and when to use it, since that one field is how Claude picks among 100+ skills; and match the degrees of freedom to the task, prose instructions where many approaches work, exact scripts with no parameters where operations are fragile (Anthropic - Skill authoring best practices (opens in a new tab)).

Scripts are executed rather than read into context, so bundling a validated utility script is both more reliable and cheaper than having the agent regenerate the code each time. The pattern’s origin at Anthropic: the team kept watching Claude write the same slide-styling Python script, so they saved it inside the skill “as a tool for his future self”; the same engineers name tools as the under-invested layer, detailed prompts paired with bare-bones tools whose “parameters are named A and B,” and state the compounding goal plainly, Claude on day 30 of working with you should be much better than Claude on day one (Anthropic engineers on skills and tools (opens in a new tab), May 2026).

Field experience qualifies the split-into-files rule. Supabase found agents lazy about reading reference files, and when they read one they tend not to read more, so everything critical moved inline into a roughly 100-line SKILL.md whose operating principle is teaching the agent how to find current information rather than what it is, “Fetch the docs, don’t replicate them” (Supabase docs render as markdown by appending .md to any URL) (Supabase Agent Skills (opens in a new tab), April 2026). Context7’s Skill Wizard takes the opposite fork for library knowledge, generating a scoped SKILL.md from current documentation on the argument that a hand-author cannot know a library comprehensively (“you don’t know what you don’t know”); both sides agree on scope, a skill per task rather than per library, otherwise just plug in the docs (Context7 Skill Wizard walkthrough (opens in a new tab), March 2026).

Skills can also be path-scoped, so a payments team’s deployment skill never auto-loads when someone works elsewhere in the monorepo (Anthropic – How Claude Code works in large codebases (opens in a new tab), May 2026).

Anthropic recommends building evaluations before writing documentation: run the task without the skill to find the real gaps, write three test scenarios, then add only enough instruction to pass them, which stops authors from documenting imagined problems (Anthropic - Skill authoring best practices (opens in a new tab)). The recommended authoring loop uses Claude on both sides: one instance drafts and refines the skill, a fresh instance uses it on real tasks, and observed failures feed back into the draft. The community version of the same loop ships in the Superpowers library, whose skill-writing skill runs the scenario without the skill for a baseline, then with it, and iterates on the gap; a reviewer who in January 2026 tested 30 skills from Vercel’s then-new directory credits that eval-gap habit as what most skill authors lack, and reports Vercel’s own React performance skill surfacing 18 issues, five critical, resolved in under 15 minutes (Testing 30 agent skills from Vercel’s directory (opens in a new tab), January 2026).

The same review points at vocabulary as an underrated skill payload: a UI skill documenting 67 interface styles and 96 palettes works because it hands the agent the lexicon (neobrutalism, liquid glass) that turns a vague request into a one-shot. Skills are executable capability, so they are also an attack surface: a malicious skill can introduce vulnerabilities or direct the agent to exfiltrate data, and Anthropic’s guidance is to install only from trusted sources and to audit an untrusted skill’s files, dependencies, and any instructions that reach untrusted network sources before use (Anthropic – Equipping agents for the real world with Agent Skills (opens in a new tab), 16 October 2025).

The continuous delivery community treats skill scope as a design rule. A skill does one thing, so a failed run points at one step. Warning signs of a skill doing too much are an “and” in its name, branches that run entirely different paths by input, and callers that use only half of it. An instruction under five or six lines stays inline in the agent definition, and a reused or independently maintained procedure moves into a skill. Skills that should survive a model change use numbered imperative steps, state their output format explicitly, and avoid delimiter syntax that only one model family responds to (MinimumCD.org and DojoConsortium.org - Agentic Architecture Patterns (opens in a new tab), as of March 2026).

Can an agent optimize a skill unattended?

An optimizer can tune a skill overnight once a measured baseline gates every change.

Skill Forge packages the eval-first loop as a repeatable optimizer. Its Skill Mode mutates a SKILL.md against assertion-based evals, while Generic Mode applies the same loop to any file set measured by a shell command. Auto mode runs without intervention; Guided mode exposes checkpoints for evals, hypotheses, diffs, scores, and continuation (GodModeAI2025 - Skill Forge (opens in a new tab)).

The setup wizard makes the baseline a gate rather than a suggestion. In Skill Mode, the configuration needs at least three evals, a 60/40 train-test split, a valid dry run, and a composite score before the first mutation. That keeps the author from optimizing against an unmeasured or broken task (GodModeAI2025 - Skill Forge (opens in a new tab)).

Each experiment makes one focused change, records its hypothesis and category, then compares the result with the current baseline. The default decision rule keeps clear gains above 0.02, reverts regressions below -0.05, and records near misses separately; a coverage matrix spreads early experiments across untouched categories before later rounds exploit the strongest ones (GodModeAI2025 - Skill Forge (opens in a new tab)).

Unattended optimization needs recovery state. Skill Forge saves a checkpoint after each experiment, compacts older history after five experiments, retries infrastructure failures once, and pauses after three consecutive crashes. That turns an overnight run into a resumable experiment record instead of a single opaque agent session (GodModeAI2025 - Skill Forge (opens in a new tab)).

The authoring talk (trigger, structure, steering, pruning) names a tradeoff the docs skip: every model-invoked skill adds context load, a description charged on every request, while user-invoked skills shift the cost to the user’s cognitive load; Superpowers leans model-invoked while the speaker’s library leans user-invoked, because a model “may just choose not to follow” a context pointer (The Missing Manual: How to Write Great Skills (opens in a new tab), June 2026). The talk’s steering device is leading words, dense terms like “vertical slice” that the agent repeats back in its reasoning traces and that outperform negative phrasings like “don’t code layer by layer”; splitting a workflow into separate skills forces legwork the model skips when it can already see the goal (the grill-with-docs skill exists because plan mode’s clarifying questions never do enough research on their own); and pruning has three named failure modes, duplication, sediment (shared docs accumulating irrelevant material nobody deletes), and no-ops, instructions that appear to do something but do not change behavior, caught with deletion tests (The Missing Manual: How to Write Great Skills (opens in a new tab), June 2026).

The same author’s follow-up post gives the no-op test concrete targets: lines such as “be thorough” or “make the commit message very detailed” restate what an agent already does by default. Remove each one and compare the output, and a line whose removal changes nothing was a no-op. The post adds that agent-authored skills carry whole paragraphs of them, and that no-ops make a skill harder to evaluate and maintain while spending tokens (Post on skill no-ops (opens in a new tab), June 2026).

Claude Code’s creator keeps about seven documented skills and frames the limit as skill debt, “the more you build, the more you owe in maintenance,” putting the sustainable number at 5-10 actively maintained skills rather than 50, since skills drift as models improve (Skills, loops, and skill debt interview (opens in a new tab), April 2026).

A published library takes the opposite bet and answers the maintenance objection with structure rather than restraint. pstack, an MIT-licensed plugin authored by a Cursor engineer and shipped in Cursor’s official plugin repository, holds one entry-point “mode” skill, roughly two dozen situational skills, and twenty-one principle skills that each carry a single rule (delete before adding, make illegal states unrepresentable, prove behavior against the running artifact rather than a self-report). The entry point is what keeps the set navigable: invoked, it opens a todo list whose first item is reading an inline index of those principles, matches the request to one of twenty-two playbooks (bug fix, perf, refactoring, visual parity, autonomous run, pause safely), copies that playbook’s steps in verbatim, and routes to the other skills as the steps fire; it is a sticky mode, staying on across turns until the user opts out (cursor - pstack (opens in a new tab), as of August 2026). Three authoring choices carry that structure. Each principle is a standalone file so other skills can invoke it by name instead of restating the rule, giving a large library one owner per rule. The matched playbook is copied into the todo list rather than linked, which is the same distrust of context pointers the authoring talk above names. And the library ships a skill that mines the user’s own transcripts to draft a personal routing skill on top of the same base, so a team can keep the principles and replace the routing (cursor - pstack (opens in a new tab), as of August 2026).

The same repository ships a skill aimed at the register of the agent’s own prose rather than at its task behavior. It names the tells that mark generated writing, has the model audit a draft against them, rewrite, and then re-apply itself on every following turn, so the correction holds across a session instead of landing once. The account is one reviewer’s subjective before-and-after with no measurement, and that reviewer distrusts detector scores as evidence (So I tried Matt’s skills… (opens in a new tab), August 2026, practitioner).

The tells such a skill hunts for are measurable in the wild. Barron’s counted the construction “it’s not X, it’s Y” in documents of large US companies: 49 in 2023, 100 in 2024 and 208 in 2025. An AI detection company cautioned that the phrase is no proof of AI use, since it was a cliche before language models adopted it (Fortune - The “it’s not X, it’s Y” phrase giving CEOs away (opens in a new tab), April 2026).

Skills also work as team memory, not just capability. Sionic AI, running 1,000+ ML experiments a day, closes the loop with two commands: /retrospective has Claude read the finished session, write the learnings up as a skill file, branch, commit, and open a PR against a team registry, and /advise pulls from that registry before new work starts, surfacing what a colleague’s experiments already established; every skill template carries a Failed Attempts table, which they report gets read more than any other section, and GitHub Actions validate plugin structure and regenerate marketplace.json so the registry maintains itself. A behavioral side effect: knowing the retrospective runs later, people explain their reasoning more clearly during sessions (How We Use Claude Code Skills to Run 1,000+ ML Experiments a Day (opens in a new tab), December 2025).

Two mechanics govern how a skill behaves once loaded. Invoked skill content enters the conversation as a single message and stays for the rest of the session, so every line is a recurring token cost, and auto-compaction re-attaches only the most recent invocation of each skill, keeping the first 5,000 tokens within a combined 25,000-token budget that fills from the most recent skill, so older skills can drop entirely (Anthropic - Extend Claude with skills (opens in a new tab)). Selection is budgeted too: names and descriptions preload so Claude knows what exists, but the listing budget scales at 1% of the model’s context window and truncates each entry at 1,536 characters, dropping the descriptions of least-used skills first, which is why the key use case must lead the description (Anthropic - Extend Claude with skills (opens in a new tab)).

Two frontmatter switches control who fires a skill: disable-model-invocation: true makes it user-only, for side-effecting commands like deploy, and user-invocable: false makes it Claude-only, for background knowledge that is not a meaningful command. A skill can also inline live shell output before Claude sees it, using !`command` preprocessing to ground instructions in the current diff, PR, or environment, and context: fork runs the whole skill as a subagent (Anthropic - Extend Claude with skills (opens in a new tab)). Skills also take arguments: $ARGUMENTS and session variables substitute into the body at invocation, argument-hint documents the expected input, and frontmatter extends to allowed-tools, compatibility, license, and metadata fields (What the docs don’t tell you about Claude Code skills (opens in a new tab), May 2026).

Triggering is probabilistic, and practitioners hit its limits. A task-management skill fired on its trigger word only sometimes, was overridden by plan mode’s built-in behavior, and went quiet when other skills loaded, which is why file-backed state (a tasks.md, requirements.md, and session.md driven by an explicit state machine) proved more reliable than trusting a skill to follow prose across sessions (Minimalist Claude Code task management workflow (opens in a new tab)). Conference audiences report the same gap, skills that have to be invoked manually, which the speaker reads as a model-training problem on skill selection (How Claude Code works (opens in a new tab), 26 December 2025). The lesson: knowledge the agent must always apply belongs in always-loaded context, not a skill that may or may not fire.

A cheap authoring trick that recurs across sources is motivating the instruction with its consequence: “your response will be read aloud by a text-to-speech engine, so never use ellipses” outperforms the bare rule, and a website-cloning skill front-loads intent wherever the model must fill in blanks, calling the technique motivational direction (15 hidden Claude Code rules (opens in a new tab), 10 December 2025; Building a UI-cloning skill (opens in a new tab), March 2026).

How do you evaluate a skill before shipping it?

One camp holds that a skill without evals should not ship, because the average gain hides tasks the skill makes worse.

A Google DeepMind staff engineer argues that a skill without evals should not ship, and draws a distinction that decides a skill’s lifespan: capability skills teach a missing or unstable capability and should be retired as models absorb it, while preference skills encode organization-specific behavior and stay valuable for as long as the preference holds (Don’t ship skills without evals (opens in a new tab), July 2026).

The scale of the effect is measured. The SkillsBench study (v4, revised 14 June 2026) runs 87 tasks across 8 domains and 18 model-harness configurations over 9,396 selected public result files, and finds curated skills lift the average pass rate from 33.9% without them to 50.5% with them, a 16.6 percentage-point gain. The gain is non-uniform: 16 of 84 comparable tasks had negative deltas, and self-generated skills underperformed the no-skills baseline on all three tested dedicated-harness configurations (arXiv - SkillsBench (opens in a new tab)). The average hides real downside, and that camp relies on a per-skill eval to show which side of it a skill falls on.

The skill-evaluation recipe is concrete. Start with 10 to 20 cases covering positive triggers, negative non-triggers, and real production traces; give each case an explicit success criterion and grade the outcome rather than whether the agent took the expected path or triggered on the first turn; isolate each run, repeat 2 to 6 trials to average out variance, and test across the actual model and harness combinations you ship on. Prefer deterministic checks (regex, SDK, model, or method assertions) wherever possible and reserve an LLM judge for the semantic or trajectory claims that resist a deterministic assertion (Don’t ship skills without evals (opens in a new tab)). The talk reports that DeepMind keeps evals beside each internal skill and blocks a change in CI unless it improves the cases or adds coverage, and offers the team’s Gemini Interactions API skill as a worked example: it used 117 cases and reached about 95% in an internal Gemini 3.1 Pro run, while the public repository reports 87% on Gemini 3 Flash and 96% on Gemini 3.1 Pro (google-gemini - gemini-skills (opens in a new tab)).

The lifecycle payoff is an ablation you keep. Run the suite with and without the skill; when the baseline holds without it, retire a capability skill, but retain its evals so a later model or harness regression reveals the moment the guidance has to return (Don’t ship skills without evals (opens in a new tab)).

Resources

Skill evaluation & optimization

Skill libraries

Authoring guidance