Skip to content
Module

Build a Claude skill, from install to testing

Claude Skills for product managers: SKILL.md anatomy, installing in claude.ai or Claude Code, writing a description that triggers, testing, security.

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

In short

A Claude Skill is a folder built around a SKILL.md file: a name, a description, then instructions that Claude loads only when your request matches the description. It turns a recurring method (feedback synthesis, spec review, PRD) into a reusable reflex. Skills work in claude.ai, Claude Code and the API, but each surface is installed separately. Quality depends mostly on the description and on testing.

What is a Claude Skill?

A Claude Skill (or Agent Skill) is a folder built around a SKILL.md file that carries metadata and instructions, sometimes alongside reference documents or scripts. Claude pulls it in on its own when a request matches its description, so you stop pasting the same long prompt into every conversation.

Anthropic describes skills as reusable, file-based resources that give Claude domain expertise: a workflow, business context, quality rules. What sets a skill apart from an instruction typed into the chat is that it is loaded on demand. You write it once, and Claude uses it whenever the task calls for it.

The key mechanism is called progressive disclosure in the official documentation. It works on three levels:

  • Metadata: the name and description of every installed skill are always present, at roughly 100 tokens per skill according to Anthropic.
  • Instructions: the body of SKILL.md only enters the context window once the skill is triggered.
  • Resources: bundled files are read only when the instructions point to them; scripts are run and only their output is read.

So you can install many skills without cluttering every conversation. The lesson how Claude decides to load a skill walks through this with PM examples.

Skill, prompt, project or MCP: what's the difference?

A prompt serves a one-off request, a claude.ai project groups conversations around shared documents and instructions, an MCP server connects Claude to external tools or data, and a skill provides a reusable method that Claude loads only when the task needs it.

Start from the question you are actually asking:

  • "I want a result now": a well-built prompt is enough. If you paste it every week, that's the sign it could become a skill.
  • "I want Claude to know this workstream": a claude.ai project keeps documents and instructions available to every conversation in that project, and only those.
  • "I want Claude to reach this tool": that is the job of an MCP (Model Context Protocol) server, which gives access to Jira, Notion or a database. The MCP course covers it.
  • "I want Claude to follow my method": that is a skill. It can rely on MCP tools too, by referring to them by their full name.

In Claude Code, two more options come into play: the CLAUDE.md file, loaded in every session, and hooks, which run a command at a set moment without relying on the model's judgment. To pick among these five options and defend your choice, see the lesson choosing between skill, CLAUDE.md, subagent, MCP and hook.

Where do skills work: claude.ai, Claude Code or the API?

Skills work in claude.ai (with code execution turned on), in Claude Code and through the Claude API with the code execution tool. A custom skill does not sync between these surfaces: you add it separately everywhere you want to use it.

The Claude Help Center explains that skills rely on the code execution environment: without it, they do not load. Availability and settings vary by plan (individual, Team, Enterprise), and on team plans an organization owner may need to turn them on. Check the help page for your account rather than assume.

  • claude.ai: Anthropic's pre-built document skills (Word, Excel, PowerPoint, PDF) plus custom skills uploaded as a ZIP. Network access depends on user or admin settings.
  • Claude Code: custom skills as folders on your disk, no upload needed. They have the same network access as any other program on your machine.
  • Claude API: pre-built skills and custom skills uploaded through the Skills API, shared across the whole workspace. They run in a container with no network access.

For a PM: claude.ai for personal use without a terminal, Claude Code for a versioned skill shared with the team.

What does a SKILL.md file look like?

A SKILL.md file starts with a YAML block, the frontmatter, fenced by two --- lines, with at least a name and a description, followed by instructions in Markdown. Extra files (references, examples, scripts) can sit in the same folder and be referenced from the body.

The minimal structure looks like this:

---
name: feedback-synthesis
description: Synthesizes user feedback into ranked themes. Use when given quotes, reviews or tickets to analyze.
---

# Feedback synthesis

## Steps
1. ...

## Output format
...

Rules for the two required fields, per the Anthropic documentation:

  • name: 64 characters max, lowercase letters, numbers and hyphens only, without the reserved words anthropic or claude.
  • description: non-empty, 1,024 characters max, no XML tags. It covers the action of the skill and the situations that call for it.

Claude Code reads extra fields too, for example disable-model-invocation to make the skill run only through the /skill-name command, or allowed-tools to pre-approve certain tools while it runs. Other surfaces do not read all of them: the full list is on the Claude Code Skills page.

For the body, Anthropic recommends fewer than 500 lines, with detail split into bundled files referenced directly from SKILL.md, one level deep. The lesson anatomy of a SKILL.md reviews each part and what stays portable across tools.

How do you install a Claude skill?

To install a skill in claude.ai, zip its folder and upload it under Customize, then Skills. In Claude Code, put the folder in ~/.claude/skills/ for yourself, or in the .claude/skills/ folder of the repository for the whole team.

In claude.ai, the Help Center describes these steps:

  1. Turn on code execution and file creation in settings, if it is not on already.
  2. Zip the skill folder: the archive must contain the folder itself at its root, with SKILL.md inside.
  3. Open Customize, then Skills, click "+", create a skill and choose the upload option.
  4. Toggle the skill on in the list, then start a new conversation to try it.

The most common upload failures Anthropic lists: a folder name that differs from name, a missing SKILL.md, an invalid character in the name or description, or a ZIP that is too large.

In Claude Code, there is nothing to upload. A ~/.claude/skills/<name>/SKILL.md folder is available in all your projects; a .claude/skills/<name>/SKILL.md folder committed to the repository is available to everyone working on it. The /skills command lists what is loaded, and /skill-name runs a skill directly. Skills can also ship inside plugins.

To follow the install step by step and confirm Claude picks up the file, see the lesson write the SKILL.md and install it. If Claude Code is new to you, the guide Claude Code for product managers covers the basics.

Which first skill should a PM write?

A good first PM skill starts from a task you repeat often, with stable requirements and an output you know how to judge: feedback synthesis, spec review, meeting notes. Describe the expected deliverable first, then write the minimum instructions needed to get it.

Three criteria help sort candidates: the task recurs every week or more often, you keep fixing the same flaws in Claude's answer, and you could hand the work to someone else if you gave them your method. Good candidates include:

  • Sorting interview quotes or reviews into themes with their frequency.
  • Reviewing a spec before handing it to the team and listing the gaps (acceptance criteria, edge cases, data).
  • Turning raw meeting notes into decisions, actions and owners.

A simple method: do the task with Claude without a skill, note what you had to clarify or correct, ask Claude to turn that into a SKILL.md, then cut everything Claude already knows. Once loaded, every line of the body takes up context.

The free template at the bottom of this page gives you a starting structure. The Claude Skills course goes further: scoping the deliverable before writing, checkable rules, choosing allowed tools, all the way to a tested, installed skill.

How do you write a description that triggers the skill?

An effective description sums up in one or two sentences the action of the skill and the situations that call for it, written in the third person, using the words you actually type in your requests. It is the only text Claude relies on to activate the skill or not.

Until a skill is triggered, Claude only knows its name and description. A vague description ("helps with documents") keeps it silent; an overly broad one makes it show up everywhere. Anthropic's best practices give a few rules:

  • Write in the third person: "Synthesizes feedback..." rather than "I can help you...".
  • Cover the what and the when: the action, then "Use when..." with the triggers.
  • Use the concrete terms from your requests: quotes, NPS, tickets, interviews, rather than generic vocabulary.
  • Pick an explicit name, lowercase with hyphens, rather than helper or tools.

Then test triggering both ways: requests that should activate the skill, phrased several ways, and nearby requests that should not. You tune a description like a search query, by trial and error. The lesson write a description that triggers at the right moment also covers who should be allowed to launch the skill.

How do you test and improve a skill?

To test a skill, prepare at least three realistic scenarios, compare Claude's answer with and without the skill, then fix the instructions based on the gaps you see. A skill that does no better than Claude alone has no reason to exist.

Anthropic recommends building evaluations before writing extensive instructions. The idea is close to a product acceptance test:

  1. Run Claude without the skill on representative tasks and note what is missing.
  2. Write three or more scenarios, each with the request, the files provided and the expected behaviors.
  3. Measure the baseline result without the skill.
  4. Write just enough instructions to close the gaps.
  5. Rerun the scenarios in a fresh conversation, compare, adjust.

Anthropic suggests drafting the skill with one Claude instance and testing it in a separate, fresh conversation on real tasks. A bundled file that is never read is either useless or poorly signposted. If you use several models, test on each.

In Claude Code, the documentation suggests comparing sessions with and without the skill and checking both automatic and manual triggering. The lesson test a skill before relying on it details the evaluation method.

Is it safe to install a skill you found online?

Not without reading it first. Anthropic recommends using skills only from trusted sources, because a malicious skill can lead Claude to call tools or run code against your interest, up to exfiltrating data. Audit every file before turning a skill on.

A skill is text, and sometimes code, that Claude follows with whatever access it has at that moment. Installing a skill is like installing software. The Anthropic documentation and the Help Center name two main risks: prompt injection and data leakage.

Before turning on a third-party skill, including one a colleague shared:

  • Read every file in the folder: SKILL.md, references, scripts, images.
  • Look for actions unrelated to the stated goal: network calls, reads of sensitive files, content sent to a URL.
  • Be wary of skills that fetch instructions from an external URL: that content can change after your audit.
  • In Claude Code, limit allowed tools and keep a human approval step for irreversible actions.

On Enterprise plans, Anthropic offers automatic scanning of skills uploaded to claude.ai, but your own reading is still needed. The lesson choose, audit and share skills provides an audit grid and the options for sharing with your team.

Free template: SKILL.md

A minimal, commented SKILL.md for a first feedback synthesis skill. Replace the bracketed parts, delete the comments, put the file in a folder named like the name field, then install it.

Download SKILL.md
---
# name: lowercase letters, numbers and hyphens, 64 characters max.
# Not allowed: the words "anthropic" and "claude". Same name as the folder.
name: user-feedback-synthesis
# description: the skill's action + the situations that call for it, third person.
# This is the only text Claude relies on to activate the skill.
description: Synthesizes user feedback (quotes, reviews, tickets, NPS answers) into themes ranked by frequency, with supporting quotes. Use when given raw feedback to analyze or when asked for a feedback summary.
---

# User feedback synthesis

## Goal
Produce a summary that [reader: e.g. the product team] can read
in two minutes to decide on the next discovery topics.

## Expected inputs
- Raw feedback: pasted text, a CSV file or a tool export.
- If the source or the time period is missing, ask before starting.

## Steps
1. Read all the feedback before grouping anything.
2. Group it into 3 to 7 themes, named with the users' own words.
3. Count the items per theme and rank from most to least frequent.
4. For each theme, quote 1 or 2 exact quotes, without rewording them.
5. Flag separately any isolated but serious feedback (security, data loss).

## Rules
- Never invent a quote or a number that is not in the data.
- Keep what users say separate from your own hypotheses.
- [Add the rule you most often fix by hand.]

## Output format
| Theme | Number of items | Representative quote |
|-------|-----------------|----------------------|

Then: "Watch-outs" (3 lines max) and "Open questions".

## Check before answering
- The item counts per theme add up to the number of items provided.
- Every quote exists word for word in the data.

## Bundled files (optional)
For product terms, read reference.md (create it in the same folder
if you have a product glossary or a prioritization grid).

Put it into practice

The “Build reliable Claude Skills for your product work” course walks you through it step by step, on your own product, all the way to the deliverable.

See the course

Frequently asked questions

Are Claude Skills free?

Skills are not sold separately: they are part of claude.ai, Claude Code and the API, but they require code execution and availability varies by plan. The Claude Help Center shows what applies to your account.

Do you need to code to create a Claude skill?

No. A skill can be a single SKILL.md written in Markdown, with instructions in plain language. Scripts are optional and serve operations that must give exactly the same result every time.

Why doesn't my skill trigger?

Most of the time, the description is too vague or does not use the words from your requests. Also check that the skill is turned on, that code execution is on, and that the folder has the same name as the name field. In Claude Code, the /skills command lists loaded skills.

Is a skill created in claude.ai available in the API?

No. According to Anthropic, custom skills do not sync between claude.ai, the API and Claude Code: each surface is installed separately. Skills turned on for a claude.ai account can, however, show up in Claude Code when you sign in with that account.

How long should a SKILL.md be?

Anthropic advises fewer than 500 lines below the frontmatter, moving detail into bundled files referenced from the body. Shorter is better: only write what Claude does not already know.

How do I share a skill with my team?

In Claude Code, commit the folder under .claude/skills/ in the repository. In claude.ai, Team and Enterprise plans let you share a skill with colleagues from the skills list, with view-only access for recipients.