Skip to content
Module
AI

What is a Claude Skill? Agent Skills for PMs

A Claude Skill (Agent Skill) is a folder holding a SKILL.md file of Markdown instructions, sometimes along with scripts, templates or reference documents. Its header gives a name and a description; Claude always has those two fields in view and loads the rest only when a request matches the description. Skills work in the Claude apps, in Claude Code and through the API.

Definition written by Alex Dionisio, Senior Product Manager. Updated November 13, 2026.

Why it matters for a PM

A skill turns a way of working into something reusable: your PRD template, your spec review checklist, your method for digging through customer feedback. Instead of pasting the same instructions into every conversation, you write them once, keep them under version control and share them with the team. For a PM, it is also a simple way to make know-how explicit, which means it can be discussed and improved.

Example

A product team builds a "user interview notes" skill. The SKILL.md file lays out the expected structure (context, problems raised, quotes, assumptions to check) and ships with a blank template. When a PM pastes an interview transcript and asks for a summary, Claude recognizes the situation from the description, loads the skill and writes the notes in the team's format.

How does Claude load a skill?

Loading happens in stages. At startup, Claude sees only the name and description of each installed skill, about a hundred tokens per skill. When a request matches a description, it reads the body of the SKILL.md file. Supporting files (references, templates, scripts) are opened only if the instructions point to them and the task needs them; a script gets executed, and the context receives just what it returns. That layering is what lets you install many skills without crowding the model's working memory.

The name follows strict rules: lowercase letters, numbers and hyphens, 64 characters at most, without the reserved words claude or anthropic. The description, capped at 1,024 characters, is the main text Claude matches a request against when deciding whether to use the skill. It deserves as much care as a good headline: what the skill does, and the words a user would actually use when asking for it.

Skill vs MCP vs CLAUDE.md vs subagent: which one should you use?

An MCP server gives Claude access to an outside system such as a ticketing tool, a database or a documentation service. A skill teaches it a way of doing things. The two pair well: an MCP server connects Claude to your analytics tool, and a skill explains how to turn that data into the weekly report leadership expects.

In Claude Code, the CLAUDE.md file is read at every session, so it suits rules that apply to the whole project. A skill, loaded on demand, suits procedures that are only needed now and then. A subagent handles a delegated task in a context window of its own, apart from the main conversation. Claude Code also lets you call a skill directly by name, like a command typed after a slash.

How do you build, test and share a skill?

Claude Code reads skills from two places: ~/.claude/skills/ for your personal ones, and, for the team's, a .claude/skills/ directory at the root of the repository, whose contents are versioned with the code and shared through git. In the Claude apps, you upload a skill as a ZIP file from the Customize area, and the feature requires code execution to be enabled. On the API side, skills are managed through dedicated endpoints. Anthropic has also published the format as an open standard that other tools can adopt.

To test a skill, run around ten real requests through it, phrased in different ways, and note which ones trigger it wrongly or not at all. On security, Anthropic's documentation advises installing skills only from trusted sources and auditing any that come from elsewhere: a malicious skill can lead Claude to call tools or move data in ways that have nothing to do with its stated purpose.

Key points

  • SKILL.md opens with a YAML header; the API and Claude apps require two fields, name and description.
  • The description drives activation, so it should cover both the job the skill performs and the situations that call for it.
  • Loading is progressive: only the description takes up context until the skill is actually needed.
  • A skill can bundle scripts that Claude runs, which calls for the same caution as installing software.

Common mistakes

  • Writing a vague description, so the skill never fires or fires at the wrong moment.
  • Installing a skill found online without reading its instructions and scripts.
  • Cramming everything into one giant skill instead of several focused ones.

Go further with Module

The courses and lessons that cover this concept:

Guides on this topic