Authoring PM-Skills¶

This guide walks you through creating new PM skills for submission to the pm-skills repository. Whether you're contributing your first skill or your tenth, this guide covers everything from concept to pull request.

Table of Contents¶

Overview
Before You Start
The Contribution Process
Skill Anatomy
Writing SKILL.md
Creating TEMPLATE.md
Writing EXAMPLE.md
Creating the Slash Command
Testing Your Skill
Quality Checklist
Submission Process
Common Mistakes
Advanced Topics

Overview¶

What Makes a Good Skill?¶

A good PM skill:

Solves a real problem — PMs actually need this artifact regularly
Produces consistent output — Same quality every time
Works across contexts — Useful for different products, teams, industries
Is well-documented — Clear instructions, useful template, realistic example
Integrates with workflows — Chains naturally with other skills

The Three Files¶

Every skill consists of three files:

skills/<skill-name>/
├── SKILL.md              # Instructions for the AI
└── references/
    ├── TEMPLATE.md       # Output structure
    └── EXAMPLE.md        # Completed example

Plus an optional slash command:

commands/<skill-name>.md  # Slash command definition

Before You Start¶

1. Check If It Already Exists¶

Review the existing repo catalog before opening a new skill proposal. The current repo contains 31 skills in skills/ (25 phase skills, 1 foundation skill, and 5 utility skills), while AGENTS.md lists the currently registered/discoverable subset.

Category	Existing Skills
research	interview-synthesis, competitive-analysis, stakeholder-summary, persona
problem-framing	problem-statement, opportunity-tree, jtbd-canvas
ideation	hypothesis, solution-brief
specification	prd, user-stories, acceptance-criteria, edge-cases, adr, design-rationale
validation	experiment-design, instrumentation-spec, dashboard-requirements
reflection	experiment-results, retrospective, lessons-log, pivot-decision
coordination	launch-checklist, release-notes, spike-summary, refinement-notes

Plus shipped non-phase skills: - foundation-persona - utility-pm-skill-builder

2. Validate the Need¶

Answer these questions:

Do PMs create this artifact at least monthly?
Would 3+ different PM roles find this useful?
Does it produce a concrete deliverable (not just advice)?
Can you describe 3+ distinct use cases?
Is it different enough from existing skills?

If you answered "no" to any, reconsider whether this is the right skill.

3. Choose the Right Category¶

Category	Use When The Skill...
`research`	Gathers or synthesizes information about users, market, or stakeholders
`problem-framing`	Defines, scopes, or articulates problems to solve
`ideation`	Explores solutions or forms testable assumptions
`specification`	Details requirements, decisions, or what to build
`validation`	Plans or instruments experiments and measurement
`reflection`	Captures learnings, retrospectives, or pivot decisions
`coordination`	Aligns teams, prepares launches, or communicates

Plus shipped non-phase skills: - foundation-persona - utility-pm-skill-builder

4. Choose Classification and Phase¶

Skills live in a flat skills/ directory, but the repo now uses two frontmatter axes:

Classification	Phase rule	Naming pattern	Examples
`domain`	`phase` is required	phase-prefixed skill name	`discover-interview-synthesis`, `deliver-prd`
`foundation`	omit `phase`	classification-driven name	`foundation-persona`
`utility`	omit `phase`	classification-driven name	`utility-<name>`

For most new PM artifact skills, use domain behavior: choose the primary lifecycle phase, then prefix the skill name with that phase for clarity and sorting.

Phase	When	Examples
`discover`	Understanding the landscape	`discover-interview-synthesis`, `discover-competitive-analysis`
`define`	Framing the problem	`define-problem-statement`, `define-hypothesis`
`develop`	Exploring solutions	`develop-solution-brief`, `develop-adr`
`deliver`	Specifying and shipping	`deliver-prd`, `deliver-user-stories`, `deliver-launch-checklist`
`measure`	Validating with data	`measure-experiment-design`, `measure-instrumentation-spec`
`iterate`	Learning and improving	`iterate-retrospective`, `iterate-lessons-log`

The Contribution Process¶

Step 1: Open an Issue¶

Before writing any code, open a "Request a Skill" issue with:

## Skill Proposal: <skill-name>

### Name
<lowercase-with-hyphens>

### Category
<one of the 7 categories>

### Classification
<domain | foundation | utility>

### Phase
<one of the 6 phases; required for domain skills, omit for foundation/utility>

### Description
<1-2 sentences: what it does and when to use it>

### Use Cases
1. <Specific scenario where this adds value>
2. <Another scenario>
3. <Another scenario>

### Example Output (Brief)
<Show a snippet of what the skill would produce>

### Why This Skill?
<Why doesn't an existing skill cover this? What gap does it fill?>

Step 2: Wait for Approval¶

Maintainers will review your proposal and may: - Approve — You're cleared to build - Request changes — Adjust the scope or approach - Suggest alternatives — An existing skill might work - Decline — The skill doesn't fit the project

Step 3: Build the Skill¶

Once approved, create your skill following this guide.

Step 4: Submit a Pull Request¶

Open a PR with: - The three required files - The slash command file - Updates to AGENTS.md (skill listing) - Confirmation that you've tested the skill

Skill Anatomy¶

Directory Structure¶

skills/
└── <skill-name>/               # lowercase-with-hyphens; domain skills are phase-prefixed
    ├── SKILL.md                # Main instructions
    └── references/
        ├── TEMPLATE.md         # Output template
        └── EXAMPLE.md          # Completed example

Naming Rules¶

Per the agentskills.io specification:

Rule	Valid	Invalid
Lowercase only	`problem-statement`	`Problem-Statement`
Hyphens for spaces	`user-stories`	`user_stories`
No consecutive hyphens	`edge-cases`	`edge--cases`
1-64 characters	`prd`	(65+ chars)
Letters, numbers, hyphens	`adr`, `v2-roadmap`	`adr!`, `v2.roadmap`
Must match directory	Dir: `prd/`, name: `prd`	Dir: `prd/`, name: `PRD`

Choosing a Name¶

Good names: - Match the repo-native skill ID: deliver-prd, iterate-retrospective, develop-adr - Are recognizable: PMs know what "PRD" means - Are searchable: Include key terms - Are concise: 1-3 words typical

Writing SKILL.md¶

The SKILL.md file is the heart of your skill. It tells the AI exactly how to create the artifact.

Required Sections¶

---
name: deliver-skill-name
description: What it does and when to use it. Include trigger keywords.
phase: deliver
# classification: foundation   # Use this instead of phase for non-domain skills
version: "1.0.0"
updated: 2026-03-19
license: Apache-2.0
metadata:
  category: specification
  frameworks: [triple-diamond, lean-startup, design-thinking]
  author: your-github-username
---

# Skill Title

<Overview paragraph>

## When to Use

- <Situation 1>
- <Situation 2>
- <Situation 3>

## Instructions

When asked to create [artifact], follow these steps:

1. **Step Title**
   Description of what to do and why.

2. **Step Title**
   Description of what to do and why.

[Continue with more steps]

## Output Contract

Use the template in `references/TEMPLATE.md` to structure the output.

## Quality Checklist

Before finalizing, verify:

- [ ] Quality criterion 1
- [ ] Quality criterion 2
- [ ] Quality criterion 3

## Examples

See `references/EXAMPLE.md` for a completed example.

Writing the Frontmatter¶

name¶

Must exactly match the directory name. Lowercase, hyphens only.

name: iterate-sprint-review  # Directory must be skills/iterate-sprint-review/

description¶

This is critical for AI discovery. Write for both humans and machines.

Structure: [Action verb] [artifact type] [key details]. Use when [trigger 1], [trigger 2], or [trigger 3].

Good example:

description: Creates a comprehensive Product Requirements Document that aligns stakeholders on what to build, why, and how success will be measured. Use when specifying features, epics, or product initiatives for engineering handoff.

Bad example:

description: Helps with PRDs.  # Too vague, no triggers

Include trigger keywords: - Action words: creates, generates, documents, designs, analyzes - Artifact names: PRD, requirements, stories, checklist - Context phrases: before launch, after experiments, for engineering

metadata.category¶

One of: research, problem-framing, ideation, specification, validation, reflection, coordination

metadata.frameworks¶

Which methodologies use this skill:

frameworks: [triple-diamond, lean-startup, design-thinking]

Options: triple-diamond, lean-startup, design-thinking, scrum, kanban, safe

phase¶

Use phase for domain skills. This is required for the 25 phase-classified PM skills.

phase: deliver

Valid values: discover, define, develop, deliver, measure, iterate

classification¶

Use classification only when the skill is not a domain skill. Foundation and utility skills omit phase.

classification: foundation

Valid values: domain, foundation, utility

Run Repo Validators¶

Before you open a PR, run the repo validators that correspond to your change:

./scripts/lint-skills-frontmatter.sh or .ps1 — skill frontmatter, description length, template structure
./scripts/validate-commands.sh or .ps1 — command file path references
./scripts/validate-agents-md.sh or .ps1 — AGENTS.md path sync for discoverable skills
./scripts/check-mcp-impact.sh or .ps1 — advisory only, but useful when adding or renaming skills

version¶

Use one quoted root version field. Do not nest version under metadata.

Always quote to prevent YAML float interpretation:

version: "1.0.0"  # Correct
version: 1.0.0    # Wrong - YAML interprets as float

updated¶

Use one root updated field with an ISO date:

updated: 2026-03-19

Writing the Overview¶

One paragraph explaining: - What artifact this skill produces - Why it matters - What value it provides

Example:

A Product Requirements Document is the primary specification artifact that
communicates what to build and why. It bridges the gap between problem
understanding and engineering implementation by providing clear requirements,
success criteria, and scope boundaries. A good PRD enables engineering to
build the right thing while maintaining flexibility on implementation details.

Writing "When to Use"¶

List 4-6 specific situations. Be concrete:

Good:

## When to Use

- After problem and solution alignment, before engineering work begins
- When specifying features, epics, or product initiatives for handoff
- When multiple teams need to coordinate on a shared deliverable
- When stakeholders need to approve scope before investment
- As reference documentation during development and QA

Bad:

## When to Use

- When you need a PRD
- For product work

Writing Instructions¶

Instructions are step-by-step directions the AI follows. Each step should:

Have a clear action title — What to do
Explain the purpose — Why it matters
Provide guidance — How to do it well

Example:

## Instructions

When asked to create a PRD, follow these steps:

1. **Summarize the Problem**
   Start with a brief recap of the problem being solved. Link to the problem
   statement if available. Ensure readers understand *why* this work matters
   before diving into *what* to build.

2. **Define Goals and Success Metrics**
   Articulate what success looks like. Include specific, measurable metrics
   with baselines and targets. These metrics should connect directly to the
   problem being solved.

3. **Outline the Solution**
   Describe the proposed solution at a high level. Focus on user-facing
   functionality and key capabilities. Include enough detail for stakeholders
   to evaluate the approach without over-specifying implementation.

Tips: - 5-10 steps is typical - Each step should be actionable - Include what information to gather - Mention what to skip or defer

Writing the Quality Checklist¶

Provide 5-8 criteria for validating output quality:

## Quality Checklist

Before finalizing, verify:

- [ ] Problem and "why now" are clearly articulated
- [ ] Success metrics are specific and measurable
- [ ] Scope boundaries are explicit (in/out/future)
- [ ] Requirements are testable and unambiguous
- [ ] Technical considerations are surfaced without over-specifying
- [ ] Dependencies and risks are documented with owners
- [ ] Document is readable in under 15 minutes

Make criteria: - Specific and verifiable - Focused on common failure modes - Actionable (can be fixed if not met)

Creating TEMPLATE.md¶

The template provides the exact structure for the output.

Template Structure¶

---
artifact: <artifact-type>
version: "1.0"
created: <YYYY-MM-DD>
status: draft
---

# <Artifact Title>

## Section 1
<!-- Guidance on what goes here -->

[Content placeholder]

## Section 2
<!-- Guidance on what goes here -->

[Content placeholder]

Template Principles¶

Use clear section headings — Match the sections in your instructions
Include HTML comments — Guide the AI on what each section needs
Provide structure hints — Tables, lists, or prose as appropriate
Keep it flexible — Don't over-constrain

Example: PRD Template (excerpt)¶

---
artifact: prd
version: "1.0"
created: <YYYY-MM-DD>
status: draft
---

# PRD: [Feature/Initiative Name]

## Overview

### Problem Statement
<!-- Brief recap of the problem. Link to full problem statement if available. -->

[Problem summary]

### Solution Summary
<!-- High-level description of what we're building -->

[Solution summary]

## Goals & Success Metrics

### Goals
<!-- What outcomes are we trying to achieve? -->

1. [Primary goal]
2. [Secondary goal]

### Success Metrics

| Metric | Current Baseline | Target | Timeline |
|--------|-----------------|--------|----------|
| [Primary metric] | [Value] | [Value] | [Date] |

## Scope

### In Scope
<!-- What will be delivered in this iteration -->

- [Feature/capability 1]
- [Feature/capability 2]

### Out of Scope
<!-- What will NOT be delivered -->

- [Excluded item 1]

Template Tips¶

Match your instructions: If instructions say "Define Goals," have a "Goals" section
Use tables for structured data: Metrics, risks, dependencies work well as tables
Include frontmatter: Helps track artifact metadata
Add placeholder guidance:  help the AI understand intent

Writing EXAMPLE.md¶

The example shows what a great output looks like. This is crucial for quality calibration.

Example Requirements¶

Complete — No placeholders, fully filled out
Realistic — Based on a believable scenario
High quality — Demonstrates what "good" looks like
Appropriately detailed — Not too sparse, not bloated

Example Structure¶

---
artifact: prd
version: "1.0"
created: 2025-01-15
status: complete
context: Project management tool adding recurring tasks feature
---

# PRD: Recurring Tasks

## Overview

### Problem Statement

Users of TaskFlow spend significant time manually recreating repetitive
tasks that occur on predictable schedules. Our research shows that 34%
of all tasks created are duplicates of previous tasks, and power users
report spending 2+ hours per week on this manual work...

[Continue with fully completed content]

Choosing an Example Scenario¶

Pick a scenario that is:

Relatable — Most PMs understand it
Representative — Shows typical complexity
Complete — Has enough depth to fill all sections
Generic — Not specific to one industry or company

Good scenarios: - E-commerce: Search, checkout, wishlist features - SaaS: User management, reporting, integrations - Productivity: Task management, collaboration, notifications

Avoid: - Highly specialized domains (medical, legal) - Controversial topics - Company-specific context

Example Quality Bar¶

Your example should demonstrate:

All template sections filled meaningfully
Realistic numbers, names, and dates
Appropriate level of detail
Professional tone
No placeholder text ([TBD], XXX)
Internally consistent

Creating the Slash Command¶

Slash commands provide quick invocation in Claude Code.

Command Structure¶

Create commands/<skill-name>.md:

---
description: <Brief description for command discovery>
---

Use the `<skill-name>` skill to <what it creates>.

Read the skill instructions from `skills/<skill-name>/SKILL.md` and follow them to create <artifact>.

Use `skills/<skill-name>/references/TEMPLATE.md` as the output format.

Context from user: $ARGUMENTS

Example: PRD Command¶

---
description: Create a Product Requirements Document
---

Use the `prd` skill to create a comprehensive Product Requirements Document.

Read the skill instructions from `skills/deliver-prd/SKILL.md` and follow them to create a PRD.

Use `skills/deliver-prd/references/TEMPLATE.md` as the output format.

Context from user: $ARGUMENTS

The $ARGUMENTS Variable¶

$ARGUMENTS captures everything the user types after the command:

/prd search feature for e-commerce
     ↑____________________________↑
              $ARGUMENTS

Testing Your Skill¶

Before submitting, thoroughly test your skill.

Test Checklist¶

Basic invocation works — Skill produces reasonable output
Template is followed — Output matches template structure
Example quality is matched — Output quality similar to example
Different contexts work — Try 3+ different scenarios
Slash command works — (If created)
Chains with other skills — Works as input/output with related skills

Testing Methods¶

Method 1: Direct Reference¶

Read skills/deliver-my-skill/SKILL.md and use it to create
[artifact] for [your test scenario].

Method 2: Slash Command¶

/my-skill "test scenario context"

Method 3: Natural Language¶

Use the my-skill skill to create [artifact] for [scenario].

Test Scenarios¶

Test with at least:

Minimal context — Just the basic request
Rich context — Detailed background information
Edge case — Unusual or challenging scenario
Different domain — Another industry or product type

What to Look For¶

Good signs: - Output follows template structure - All sections are meaningfully filled - Quality matches your example - Consistent results across tests

Warning signs: - Sections are skipped or empty - Output doesn't match template - Quality varies wildly - AI asks too many clarifying questions

Quality Checklist¶

Before submitting your PR, verify:

File Structure¶

Directory path is skills/<skill-name>/
Contains SKILL.md
Contains references/TEMPLATE.md
Contains references/EXAMPLE.md
Slash command at commands/<skill-name>.md

Frontmatter¶

name matches directory name exactly
description is 50-300 characters with trigger keywords
Either phase or classification is correct for the skill type
category is one of the 7 valid values
Root version is quoted ("1.0.0")
updated uses YYYY-MM-DD
license is Apache-2.0

SKILL.md Content¶

Overview paragraph explains value
4-6 "When to Use" situations
5-10 clear instruction steps
References template and example
5-8 quality checklist items

TEMPLATE.md¶

Frontmatter with artifact type
Clear section structure
HTML comments with guidance
Matches instruction steps

EXAMPLE.md¶

Complete (no placeholders)
Realistic scenario
Demonstrates quality bar
Follows template exactly

Testing¶

Tested with 3+ scenarios
Output matches template
Quality matches example
Slash command works

Submission Process¶

1. Fork the Repository¶

# Fork via GitHub UI, then clone your fork
git clone https://github.com/YOUR-USERNAME/pm-skills.git
cd pm-skills

2. Create a Branch¶

git checkout -b skill/<skill-name>

3. Add Your Files¶

skills/<skill-name>/
├── SKILL.md
└── references/
    ├── TEMPLATE.md
    └── EXAMPLE.md

commands/<skill-name>.md

4. Update AGENTS.md¶

Add your skill to the appropriate section:

#### <skill-name>
**Path:** `skills/<skill-name>/SKILL.md`

<Your description from frontmatter>

Add the command to the Commands section:

| `/<skill-name>` | <Brief description> |

5. Commit and Push¶

git add .
git commit -m "feat: add <skill-name> skill"
git push origin skill/<skill-name>

6. Open a Pull Request¶

Include in your PR description:

## New Skill: <skill-name>

### Closes
#<issue-number> (link to approved proposal)

### Description
<Brief description of what the skill does>

### Testing
- Tested with [scenario 1]
- Tested with [scenario 2]
- Tested with [scenario 3]

### Checklist
- [ ] SKILL.md complete with valid frontmatter
- [ ] TEMPLATE.md provides clear structure
- [ ] EXAMPLE.md is complete and realistic
- [ ] Slash command created
- [ ] AGENTS.md updated
- [ ] Tested with multiple scenarios

Common Mistakes¶

Mistake 1: Vague Description¶

Bad:

description: Helps create roadmaps

Good:

description: Creates a product roadmap document with prioritized initiatives, dependencies, and timeline. Use when planning quarters, communicating strategy to stakeholders, or aligning teams on priorities.

Mistake 2: Instructions Too Abstract¶

Bad:

1. **Think about the problem**
   Consider what matters.

Good:

1. **Define the Problem Scope**
   Identify the specific user segment affected, the pain point they experience,
   and the business impact of not solving it. Quantify where possible.

Mistake 3: Template Doesn't Match Instructions¶

If instructions say "Define success metrics," the template needs a "Success Metrics" section.

Mistake 4: Incomplete Example¶

Placeholders like [TBD] or TODO in your example mean the AI won't know what complete looks like.

Mistake 5: Wrong Category¶

Choosing ideation for something that's clearly specification confuses organization and discovery.

Mistake 6: Name Doesn't Match Directory¶

Directory: skills/deliver-product-roadmap/
Frontmatter: name: roadmap  # WRONG - must be "deliver-product-roadmap"

Advanced Topics¶

Supporting Multiple Frameworks¶

Your skill can work across methodologies:

metadata:
  frameworks: [triple-diamond, lean-startup, design-thinking, scrum]

Consider how the skill fits each: - Triple Diamond: If classification is domain, which phase does it belong to? - Lean Startup: Is it Build, Measure, or Learn? - Design Thinking: Which stage? - Scrum: Which ceremony or artifact does it support?

Creating Skill Chains¶

Design your skill to work with others:

Inputs from:

## When to Use

- After completing a problem-statement to define testable assumptions
- Building on insights from interview-synthesis

Outputs to:

## Next Steps

After creating this artifact, consider:
- Using the `prd` skill to specify detailed requirements
- Running `experiment-design` to validate assumptions

Handling Skill Variants¶

If your skill could have variants (e.g., "lightweight PRD" vs "comprehensive PRD"), consider:

One flexible skill with instructions for different depths
Separate skills if the process differs significantly

Generally prefer one flexible skill unless workflows are truly different.

Internationalization Considerations¶

Skills should work globally: - Avoid US-specific terminology without explanation - Use ISO date formats (YYYY-MM-DD) - Note when concepts are region-specific

Resources¶

Templates¶

Start with the skill template:

docs/templates/skill-template/
├── SKILL.md
└── references/
    ├── TEMPLATE.md
    └── EXAMPLE.md

References¶

Frontmatter Schema — Detailed field documentation
Categories Reference — Category definitions
agentskills.io Specification — Base specification
Existing Skills — See how others are structured

Getting Help¶

Open an issue for questions
Review existing skills for patterns
Ask in your proposal issue before building

Quick Start Checklist¶

Ready to create a skill? Here's the fast path:

Open "Request a Skill" issue → wait for approval
Copy docs/templates/skill-template/ to skills/<name>/
Write SKILL.md with frontmatter, instructions, checklist
Create TEMPLATE.md matching your instruction steps
Write complete EXAMPLE.md (no placeholders!)
Create commands/<name>.md slash command
Test with 3+ scenarios
Update AGENTS.md
Submit PR with checklist complete

Part of PM-Skills — Open source Product Management skills for AI agents