How to Write a Product Management Skill for Claude Code

A Claude Code skill is a folder containing a SKILL.md file and any supporting resources, picked up automatically by the agent and loaded only when needed. Writing one for product management work means you stop re-typing the same playbook into chat and start running your PRD process, your discovery cadence, and your release-notes voice on rails. This guide walks through the anatomy of a PM skill, why the YAML frontmatter description field decides whether your skill ever gets used, and a complete working example you can paste into your repo today.

What Is a Claude Code Skill?

Anthropic launched Skills in October 2025 and formalized them as an open standard at agentskills.io. A skill is a directory — typically .claude/skills/<your-skill>/ for a project, or ~/.claude/skills/ for personal use — containing a SKILL.md and any number of bundled scripts, references, or templates.

The mechanic that matters is progressive disclosure, three loading levels that the runtime manages for you:

1. Metadata (always loaded). Just name and description from the frontmatter — about 100 tokens per skill. This is the only thing Claude sees when deciding which skill to use.
2. Instructions (loaded on trigger). The body of SKILL.md. Anthropic's best-practices doc recommends keeping this under 500 lines.
3. Resources (loaded on demand). Linked files Claude reads via Bash, scripts it runs without ever loading their source into context. Effectively unlimited token budget.

"Each skill only takes up a few dozen extra tokens, with the full details only loaded in should the user request a task that the skill can help solve. GitHub's official MCP on its own famously consumes tens of thousands of tokens." — Simon Willison, Claude Skills are awesome, maybe a bigger deal than MCP (Oct 2025)

For a product manager, that means you can carry a library of frameworks, templates, and team conventions with you into every Claude Code session — without paying for them in context until the moment you need them.

Why PMs Should Write Their Own Skills

There are now hundreds of pre-built PM skills available — Anthropic ships an official Product Management plugin, Dean Peters' Product-Manager-Skills repo has 47 skills and 3.9k stars, and the Snyk team published a curated top-7 list earlier this year. Installing one of these is a fine starting point.

But your team's PRD has a structure. Your discovery process names assumptions in a particular way. Your release notes have a voice. Someone else's skill encodes someone else's defaults — and the moment your team's work doesn't fit that mold, you're back to pasting prompts into chat.

"The real unlock for product managers isn't simply using AI to answer your questions — it's instead in building AI-powered systems and workflows that actually automate the work we do every day." — Sachin Rekhi, Claude Code for Product Managers

A skill you author yourself encodes your PRD shape, your customer interview synthesis template, your prioritization framework. It also evolves as your team's process evolves — version-controlled in the repo right next to the code it describes.

The Anatomy of a PM Skill

Every skill starts with a directory. The minimum viable PM skill is two things: a directory and a SKILL.md inside it.

.claude/skills/
└── draft-prd/
    └── SKILL.md

That's it. Drop that into any repo with Claude Code installed, restart the agent, and /draft-prd becomes a slash command.

The body of SKILL.md is markdown with YAML frontmatter at the top:

---
name: draft-prd
description: Drafts a product requirements document from a feature concept. Use when the user wants a PRD, spec, or feature brief, or mentions writing scope, acceptance criteria, or non-goals.
---
[your instructions here]

The full set of frontmatter fields Claude Code supports goes well beyond name and description. Here are the ones a PM skill is most likely to use:

For most PM skills you'll only set name and description. Everything else is for when you need it.

How to Write a Description That Actually Triggers

The description field is the most important text you will ever write. It is the only thing Claude reads when deciding whether to load your skill — there is no algorithmic routing, no semantic search, no embedding lookup. The model reads a flat list of skill descriptions and decides via language understanding alone.

This is where most skills die. Vague descriptions never get triggered. Workflow-summarizing descriptions get triggered, but Claude follows the description and skips reading the body. Both are silent failures.

Here is the formula that works, distilled from the Anthropic best-practices doc, the obra/superpowers writing-skills guide, and Nick Babich's 7 Rules for Effective Claude Code Skills:

1. Third person, always. "Drafts a PRD…" — never "I help you write…" or "You can use this to…". Anthropic flags first/second person as a documented cause of "discovery problems."
2. Both halves required. What the skill does + when to use it. A description without a "when" is the most common reason skills go unused.
3. Front-load trigger keywords. The character budget can truncate. Lead with the words a PM would actually say: PRD, spec, feature brief, scope, acceptance criteria.
4. Be slightly pushy. Anthropic explicitly recommends phrasings like "Make sure to use this whenever the user mentions…" Models tend to under-trigger.
5. Don't summarize the workflow. A description that says "code review between tasks" caused Claude to do one review when the skill body required two. The fix: describe triggering conditions only.

"The description is critical for skill selection. Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details." — Anthropic, Skill authoring best practices

A good description for a PM skill, before and after:

Before: Helps with writing PRDs.

After: Drafts a product requirements document from a feature concept. Use when the user wants a PRD, spec, feature brief, or one-pager, or mentions defining scope, acceptance criteria, non-goals, MVPs, or what to cut. Make sure to use this whenever the user is starting a new feature.

Step-by-Step: Build a /draft-prd Skill in 30 Minutes

Here is a working PM skill end-to-end. Copy this into your repo and you have a project-scoped slash command that drafts PRDs in your team's voice.

Step 1 — Create the directory

From the root of any repo with Claude Code:

mkdir -p .claude/skills/draft-prd

Project-scoped skills live in .claude/skills/. Personal skills (used across all your projects) live in ~/.claude/skills/. For team skills, project scope wins — the skill ships with the repo.

Step 2 — Write the frontmatter

Create .claude/skills/draft-prd/SKILL.md and start with the YAML block:

---
name: draft-prd
description: Drafts a product requirements document from a feature concept. Use when the user wants a PRD, spec, feature brief, or one-pager, or mentions defining scope, acceptance criteria, non-goals, MVPs, or what to cut. Make sure to use this whenever the user is starting a new feature.
---

Step 3 — Define the role and the structure

The body of SKILL.md is the prompt Claude follows when the skill activates. For a judgment-heavy task like PRD drafting, give Claude a role, a fixed output structure, and a forcing function on the upstream questions.

# Draft a PRD

You are acting as a senior product manager drafting a PRD. The reader is the
engineering team — they should be able to estimate, scope, and ask sharp
questions after reading.

## Required upstream questions

Before writing anything, ask the user for:

1. The user / persona this is for (be specific — not "users")
2. The job-to-be-done in their own words
3. The smallest version that proves the bet
4. What's explicitly _not_ in scope (the non-goals)
5. The success metric — what would make this feel like a win in 6 weeks

If any answer is vague, push back once with a concrete clarifying question.
Do not start drafting until all five are answered.

## Output structure

Once you have answers, produce a PRD with these sections in order:

### Problem

1-2 sentences on the user pain. Concrete, not abstract.

### Audience

The persona, sized if possible.

### Solution

What we're building, in plain English. No implementation detail yet.

### Scope

- What's in (3-7 bullets, INVEST-shaped user stories)
- What's out (the non-goals from upstream)

### Acceptance criteria

Given/When/Then format. One per user story.

### Success metric

The 6-week win condition. Include the measurement source.

### Open questions

Anything we haven't answered. Don't fake confidence.

## Voice and quality bar

- Plain language. No PM jargon ("synergy", "leverage", "delight").
- Concrete examples beat abstractions.
- If you're tempted to write "users want X", instead write "[persona] does
  [task] and currently has to [workaround] because [reason]".
- Bullets shouldn't be longer than two lines.

## What this skill does NOT do

- It does not estimate engineering work. That's the team's job.
- It does not commit to a deadline. Capacity decisions happen elsewhere.
- It does not write release notes. Use /release-notes for that.

Step 4 — Add bundled resources (optional)

If your team has reference material — a personas doc, a positioning brief, an example "great PRD" — drop those in the same folder and link to them from SKILL.md:

.claude/skills/draft-prd/
├── SKILL.md
├── personas.md
└── exemplar-prd.md

In SKILL.md, link to them naturally: For persona details, see [personas.md](personas.md). Claude will only load these on demand, so you can include long reference docs at almost zero token cost.

Step 5 — Test it

Restart Claude Code (or trust the live-reload). Then in a fresh session:

> I want to add a feature where users can pin documents to the top of their workspace.

If the description is right, Claude will recognize this as a PRD-drafting moment and either invoke /draft-prd automatically or surface it. You can also trigger it explicitly:

> /draft-prd document pinning

Test the negative path too — questions that should not trigger the skill:

> Why is this build failing?

If /draft-prd activates here, your description is too broad. Tighten the "use when" clause.

Step 6 — Iterate on description, then body

Run the skill on three real feature concepts. Note where the output is wrong, the questions are missing, or the voice drifts. Edit SKILL.md and run again. Anthropic's skill-creator recommends building a 20-query eval set — should-trigger and should-not-trigger — before you ship a skill across a team.

Five PM Skill Patterns Worth Building

Once you've shipped one, these are the skill shapes with the highest leverage for PM work, drawn from what's working across the open-source PM-skill ecosystem in early 2026:

• /draft-prd — the one above. Encodes your team's PRD shape, voice, and forcing questions.
• /synthesize-research — takes a folder of customer-interview transcripts and produces themed pattern detection plus surprise findings. Sachin Rekhi's Whisper-to-synthesis pipeline is the canonical example.
• /competitive-brief — fixed matrix structure, optional WebFetch tool wired in to refresh competitor pricing pages.
• /prioritize-rice — encodes one prioritization framework (RICE, ICE, or MoSCoW) and applies it consistently across a backlog.
• /release-notes — reads recent commits, applies your team's voice, drafts release notes ready for editing.

The pattern across all of them: fixed structure plus variable input. That's the shape of work where a skill beats a one-shot prompt.

Common Mistakes When Authoring PM Skills

• First-person descriptions. "I help you write PRDs" — Anthropic explicitly flags this as a discovery breaker.
• Workflow-summarizing descriptions. If the description tells Claude what the skill does step by step, Claude will do that and skip reading the body.
• A 1,000-line SKILL.md. Move long reference material into bundled files. Keep the body under 500 lines.
• Recipe-style instructions for judgment work. Over-constrained PRD skills produce wooden, generic PRDs. Match degrees of freedom to the fragility of the task — high freedom for PRD voice, low freedom for "do not modify the migration command."
• Skipping the eval pass. Run your skill on three real cases before sharing it. Anthropic's authoring docs are emphatic: "Build evals before writing prose."
• Trusting community skills blindly. Snyk's audit of the public skills ecosystem found prompt injection in 36% of skills tested and 1,467 malicious payloads across the ecosystem. Read every line of any skill you install.

Distributing Skills Across Your Team

Three scopes, in order of how widely they propagate:

1. Personal (~/.claude/skills/) — your laptop only. Where you prototype.
2. Project (.claude/skills/ in the repo) — ships with the codebase. Every teammate who clones gets it. This is the right home for team skills.
3. Plugin (a published Claude Code plugin) — distributed via the plugin marketplace, namespaced as plugin-name:skill-name. Worth doing once you have 5+ stable skills.

Project scope is almost always the right answer for team work. The skill version-controls alongside the process it encodes, and changing the process is a normal pull request.

"Create a skill when you keep pasting the same playbook, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact." — Claude Code docs, Extend Claude with skills

FAQ

What's the difference between a skill and a slash command? In Claude Code today, custom slash commands (.claude/commands/) and skills (.claude/skills/) are unified — both produce a /name command. Skills are the recommended path going forward because they support bundled resources, scoped tool permissions, and Claude-side auto-invocation.

Do PMs need to know YAML? The frontmatter is YAML, but the only fields that matter for a first skill are name and description. Both are single-line strings. The rest of SKILL.md is plain markdown.

How long should a SKILL.md be? Under 500 lines for the body, ideally under 200 for skills you use frequently. Push reference material into bundled files (personas.md, exemplar.md) and link to them — Claude loads them on demand at near-zero context cost.

Can a skill call Linear, Jira, or Slack? Yes — combine your skill with MCP tools or use allowed-tools in the frontmatter to pre-approve specific tool access (Read, Edit, Bash, WebFetch). For deeper integrations, MCP servers expose Linear/Jira/Slack as callable tools the skill can orchestrate.

Where do skills go wrong most often? The description. If a skill never triggers, your description is vague or in first person. If a skill triggers but produces wrong output, your description is summarizing the workflow instead of the trigger conditions. Fix the description first.

Next Steps

The leverage compounds. One skill removes one repetitive PM task from your week. Five skills make Claude Code feel like an opinionated PM workflow engine. The teams getting outsized value from AI in product right now aren't the ones using more tools — they're the ones encoding their actual process into version-controlled, agent-executable form.

If you want more on the broader shift this enables, our pieces on spec-driven development, the AI coding bottleneck moving to PM, and how Claude Code plugins are turning engineers into PMs are good follow-ups.

Start with one skill. The right one is whatever you've pasted into chat three times this month.