Skip to content
TilloTech Docs

Anthropic: skills

Source: Extend Claude with skills

Checked: 13 July 2026. Claude Code has merged custom commands into skills; legacy .claude/commands/*.md files remain supported.

Evidence type: product documentation for an implementation of the Agent Skills open standard, plus authoring and evaluation recommendations.

When a skill is appropriate

Create a skill for repeatedly pasted instructions, a checklist, a multi-step procedure, or a procedural section that has outgrown the root instruction file. Reference knowledge runs inline with current work; task skills describe a specific operation and often deserve manual invocation.

Only discovery metadata is always present. The body loads when invoked and remains in context across subsequent turns, so it still needs to be concise. Supporting references, examples, templates, assets, and scripts allow deeper progressive disclosure. Anthropic suggests keeping the entry file under 500 lines and explicitly linking each support file with when to use it.

A concrete project skill has this shape:

.claude/skills/summarize-changes/
├── SKILL.md
├── template.md
├── examples/
│   └── sample.md
└── scripts/
    └── validate.sh

SKILL.md is the only required file. The directory name becomes the default command name. A skill and legacy command with the same name resolve to the skill.

Scope and precedence

Skills can be managed organisation-wide, personal, project-local, nested below the working directory, or packaged in a plugin. Enterprise overrides personal, personal overrides project, and those scopes can override bundled skills. Plugin skills are namespaced, avoiding those collisions.

Nested skills become available when work enters their directory. Conflicting nested names remain addressable through directory-qualified names. Skills from an --add-dir directory are discovered, while a settings-only additional directory grants file access without discovering skills.

Routing metadata and controls

The description states what the skill does and when it applies; Anthropic recommends putting the most important trigger first because description and supplemental trigger text may be truncated. Path globs can further limit automatic activation.

Important controls include:

  • manual-only invocation for deployment, commit, or outbound-message workflows;
  • model-only background knowledge hidden from the command menu;
  • pre-approved tools used while the skill is active;
  • tools removed while an autonomous skill runs;
  • per-turn model and reasoning-effort selection;
  • forked execution in a named subagent;
  • hooks scoped to the skill lifecycle;
  • arguments, session, project, and skill-directory substitutions.

The frontmatter contract includes name, description, when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, model, effort, context, agent, hooks, paths, and shell. The combined discovery text from description and when_to_use is capped at 1,536 characters, so the key trigger must come first.

  • Default: the user and model can invoke the skill, and it is listed to the model.
  • disable-model-invocation: true: the user can invoke the skill, the model cannot, and it is not listed to the model.
  • user-invocable: false: the model can invoke the skill, the user cannot, and it is listed to the model.

allowed-tools pre-approves listed tools; it does not remove other tools. Deny rules remain the mechanism for forbidding tools.

Menu visibility is not a security control. Preventing model invocation requires the dedicated invocation field or a permission rule. Skills that pre-approve tools deserve the same security review as executable automation.

Dynamic context and execution

Skills may preprocess the entry file with shell commands before the model sees it, producing a prompt grounded in current diffs, PR data, or environment versions. This is execution, not inert documentation. Organisations can disable skill shell expansion by policy. The output is inserted once as plain text and is not recursively evaluated.

Dynamic values include $ARGUMENTS, positional $0/$ARGUMENTS[0], named arguments, ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, and ${CLAUDE_SKILL_DIR}. A shell-injection fence beginning with three backticks and ! supports multi-line preprocessing. Managed disableSkillShellExecution can disable this execution for user, project, plugin, and additional-directory skills.

Forked skills isolate high-volume research or execution and return a summary to the main conversation. This can protect the main context, but the fork’s full tool and permission configuration still matters.

Evaluation

The documented skill-creator workflow creates or improves the skill, builds eval prompts and assertions, runs isolated sessions, grades with evidence, aggregates pass rate, time, and tokens, and iterates. Blind comparison helps distinguish an actually better revision from one that merely looks more detailed to its author.

Anthropic separates two questions:

  1. Does the skill trigger on the requests it should and avoid the ones it should not?
  2. Once invoked, does it produce the intended result?

It recommends realistic prompts, fresh sessions, a with-skill/without-skill baseline, and isolated cases. Its documented evaluation workflow stores cases and assertions, grades with evidence, benchmarks pass rate/time/tokens, performs blind version comparisons, tunes descriptions using trigger and non-trigger sets, and supports qualitative review.

Context lifecycle

Invoking a skill renders SKILL.md into one conversation message; Claude Code does not reread the file on every later turn. During compaction it reattaches the most recent invocation of each skill, keeping at most the first 5,000 tokens per skill within a combined 25,000-token budget, newest first. Older or large skills can therefore disappear after compaction, making concise entry files and explicit reinvocation part of long-run reliability.

Discovery-budget failure modes

With many skills, the listing budget can shorten descriptions, beginning with infrequently used skills. That can remove trigger words and reduce routing quality. Anthropic recommends inspecting the actual listing cost, trimming and front-loading descriptions, hiding low-priority entries or listing only their names, and raising the budget only deliberately.

Standards implications

  • Standardise skill routing contracts and invocation safety fields across EOS.
  • Require support files for large examples instead of a monolithic entry file.
  • Test routing, output, cost, and latency separately in clean contexts.
  • Treat dynamic context, scripts, and pre-approved tools as executable supply-chain surface.
  • Track discovery-budget pressure and retire unused skills.