Skills

A focused capability a Claude agent can adopt for one kind of task.

What it is

A Skill is a folder containing a SKILL.md file (markdown with YAML frontmatter) plus optional scripts and reference files. The frontmatter tells Claude when to activate the skill; the body tells it what to do. Skills are filesystem-based in Claude Code, Claude Desktop, and Cowork, and uploaded as a .zip on Claude.ai. The SKILL.md format is now an open standard adopted by Codex CLI, Cursor, Gemini CLI, and GitHub Copilot — same file, multiple agents.

Skills add focused know-how, not new APIs. If you need network access, pair a skill with an MCP server.

When to use it

  • You have a repeatable workflow (e.g., “write a clinical trial protocol”) with specific conventions.
  • You want Claude to auto-apply a procedure when the user’s request matches a description.
  • You want to ship a /skill-name invocation alongside autonomous activation.
  • You need to bundle small helper scripts with the prompt.

How to install / enable

Put the skill folder under ~/.claude/skills/ (personal, all projects) or .claude/skills/ (project, committed to the repo). Only SKILL.md is required.

mkdir -p ~/.claude/skills/my-skill
# place SKILL.md inside ~/.claude/skills/my-skill/

To browse and install skills shipped via a plugin marketplace, type /plugin inside Claude Code. List active skills with /skills — the picker has a type-to-filter search box for long lists. A plugin with a root-level SKILL.md (no skills/ subdirectory) is now surfaced as a skill automatically. /usage breaks down current usage by skill, subagent, plugin, and MCP server. After editing a SKILL.md, run /reload-skills to re-scan directories without restarting the session (v2.1.152, May 2026).

Skills can narrow Claude’s tool access while active. Add a disallowed-tools: list to the YAML frontmatter (v2.1.152+) to remove specific tools — useful for read-only or audit skills that should not touch Edit / Write.

Common pitfalls

  • Nesting one level too deep. The path must be ~/.claude/skills/<name>/SKILL.md, not ~/.claude/skills/<name>/<subdir>/SKILL.md.
  • Missing or invalid YAML frontmatter — Claude won’t auto-trigger the skill.
  • Treating Skills as a substitute for MCP. Skills carry instructions; MCP carries tool calls.
  • Installing skills from untrusted sources without reading SKILL.md first.

See also

Sources