lockstep

Agent Skills (Claude Code)

Skills are packaged instructions an agent loads only when relevant. In Claude Code, a skill is a SKILL.md file in .claude/skills/, shared through the repo.

A skill is a packaged set of instructions an AI agent loads only when it needs them. In Claude Code, a skill is a folder containing a SKILL.md file, plus any supporting files.

How Claude Code skills work

Per Anthropic's skills documentation:

  • Project skills live at .claude/skills/<skill-name>/SKILL.md and are shared with everyone who works in the repository once committed.
  • The frontmatter description tells Claude when the skill is relevant, and Claude loads it automatically when a prompt matches. You can also run it directly with /skill-name.
  • Set disable-model-invocation: true if a skill should only run when you ask, for example a deploy.
  • A skill's body loads only when used, unlike CLAUDE.md, which loads in full every session.

That last point is why skills matter for context rot: long procedures stay out of the context window until a task needs them.

When to use one

Use a skill for repeatable procedures: cutting a release, adding a migration, writing an ADR. A worked example is the ADR-writing skill in ADR for AI agents. For distributing skills across many repositories, teams use a plugin marketplace, covered in Claude Code team memory. For six examples, see Claude Code skills: 6 examples. For built-in commands, see the slash commands cheat sheet.

For the format shared across Claude Code, Codex, and Cursor, see the Agent Skills open standard.

What is a Claude Code skill?
A folder with a SKILL.md file of instructions, and optional supporting files, that Claude Code loads when it is relevant or when you invoke it with /skill-name. Its body loads only when used, so long reference material costs little until needed.
Where do Claude Code skills live?
Project skills live in .claude/skills/<skill-name>/SKILL.md and are shared with the team when committed. They can also be packaged as plugins and distributed through a plugin marketplace.
What is the difference between a skill and CLAUDE.md?
CLAUDE.md loads in full at the start of every session, so it should hold short, always-relevant instructions. A skill's body loads only when it is used, so it suits longer procedures that only matter for some tasks.

Related