# Contributing to Product Manager Skills

Thanks for your interest in contributing! This repository helps product managers work better with AI by providing battle-tested PM frameworks in an agent-ready format.

---

## 🎓 Design Philosophy — Read This First

As much as this repo is for adding skills to your agent, it's equally tasked to **help product managers become more awesome at their craft — and to help them send the ladder down to others.**

Skills here serve both goals simultaneously: they equip AI agents to do PM work at a professional level, and they teach the human PM the *why* behind the framework so they can explain it, adapt it, and pass it on.

**ABC — Always Be Coaching** is a key governing principle.

Every skill should:
- Explain the *why*, not just the *what*
- Name failure modes so the reader recognizes them in the wild
- Show reasoning in examples, not just outputs
- Leave the user with better judgment, not just a filled-in template

**The most common contribution mistake:** trimming explanation to tighten copy. Brevity that strips learning scaffolding is a defect, not an improvement. If you're shortening a skill, check that you're cutting fluff — not cutting the lesson.

---

## 🎯 Who Can Contribute?

**Anyone!** You don't need to be technical. If you:
- Have a PM framework that works consistently
- Spotted an error or gap in an existing skill
- Want to improve examples or clarity
- Have feedback on what's missing

...then you can contribute.

---

## 🤔 What Can You Contribute?

### 1. **New Skills**
Have a PM framework that should be included? Submit it!

**Examples of good candidates:**
- A template you use repeatedly (like OKR writing, stakeholder mapping, etc.)
- A process you follow consistently (like feature launches, go-to-market planning)
- A decision framework that helps you choose between options

**Not a good fit:**
- One-off advice or tips (these should be prompts, not skills)
- Company-specific processes (skills should be universally applicable)
- Overly complex frameworks (skills should be actionable, not academic)

---

### 2. **Improvements to Existing Skills**
Found something unclear? Missing examples? Outdated advice?

**Good improvements:**
- Add a "bad example" showing what NOT to do
- Clarify ambiguous instructions
- Add references to related skills
- Fix errors or typos
- Improve formatting for readability

**Please avoid:**
- Removing opinionated guidance (we take stances, not just list options)
- Adding fluff or unnecessary explanations (every word should earn its keep)
- Changing the standard structure (all skills follow the same format)

---

### 3. **Feedback & Suggestions**
Not ready to write? That's fine—share ideas:
- What PM tasks do you struggle with?
- Which existing skills are most/least useful?
- What frameworks do you wish existed?

**Open an issue** and we'll discuss.

---

## 📝 How to Contribute (Step-by-Step)

### For Non-Technical PMs (No GitHub Experience Required)

**Option 1: Email Your Suggestion**
1. Write up your idea in a doc (Google Docs, Word, etc.)
2. Email it to [Dean's email - add if you want]
3. We'll review and format it for you

**Option 2: Open a GitHub Issue**
1. Go to the [Issues tab](https://github.com/deanpeters/Product-Manager-Skills/issues)
2. Click "New Issue"
3. Describe your suggestion:
   - **For new skills:** What's the framework? When would a PM use it?
   - **For improvements:** Which skill? What section? What's unclear or wrong?
4. Submit—we'll follow up

---

### For Technical PMs (Comfortable with GitHub)

**Option 1: Fork & Pull Request**
1. **Fork this repository** (button in top-right)
2. **Clone your fork** to your computer:
   ```bash
   git clone https://github.com/YOUR-USERNAME/Product-Manager-Skills.git
   cd Product-Manager-Skills
   ```
3. **Create a new branch:**
   ```bash
   git checkout -b add-skill-name
   ```
4. **Make your changes** (add a skill, improve existing content)
5. **Commit your changes:**
   ```bash
   git add .
   git commit -m "Add [skill-name] skill"
   ```
6. **Push to your fork:**
   ```bash
   git push origin add-skill-name
   ```
7. **Submit a pull request** on GitHub

**We'll review within a week and provide feedback.**

---

**Option 2: Use the Add-a-Skill Utility (Automated)**

For faster skill creation, use the `add-a-skill.sh` utility to automatically generate skills from raw PM content:

```bash
# From a file
./scripts/add-a-skill.sh research/your-framework.md

# From clipboard
pbpaste | ./scripts/add-a-skill.sh

# Check available adapters
./scripts/add-a-skill.sh --list-agents
```

**What it does:**
1. Analyzes your content and suggests skill types
2. Generates complete skill files with proper structure
3. Validates metadata for marketplace compliance
4. Updates documentation automatically
5. Stages files for git commit

**Supported adapters:** Claude Code, Manual mode (`--agent manual`), and custom adapters

**Learn more:** See [`docs/Add-a-Skill Utility Guide.md`](docs/Add-a-Skill%20Utility%20Guide.md)

**Want a guided wizard instead?**
```bash
./scripts/build-a-skill.sh
```

**Find and test before opening a PR:**
```bash
# Find related skills by keyword/type
./scripts/find-a-skill.sh --keyword discovery --type interactive

# Test your new/updated skill
./scripts/test-a-skill.sh --skill your-skill-name --smoke
```

---

## Using AI Agents (Optional)
If you use OpenAI Codex while drafting or validating skills, open this repo in your Codex workspace and reference the skill file path directly (e.g., `skills/user-story/SKILL.md`). For a quick walkthrough, see [Using PM Skills with Codex](docs/Using%20PM%20Skills%20with%20Codex.md).

For guidance on how to manually distill frameworks and source material into new skills, see [Building PM Skills](docs/Building%20PM%20Skills.md).

---

## 🔒 Security, Safety, and Evaluation

- Review any source material and scripts for unsafe or destructive actions. Skills should not request secrets or run risky commands.
- If you add a script, place it in `skills/<skill-name>/scripts/`, keep it deterministic, avoid network calls, and document usage in the skill file.
- Run a quick dry run using the skill questions or template and refine `name`, `description`, and steps until outputs are consistent and specific.

---

## 🧩 Skill Types: Which One to Create?

Before adding a new skill, determine which type it should be:

### **Component Skills** (Templates & Artifacts)
**Use when:** You need a reusable template for creating a specific PM deliverable.

**Examples:**
- User story template
- Positioning statement format
- Epic hypothesis structure
- PRD section (problem statement, success metrics)

**Structure:**
- Focused on "how to create X well"
- Includes template + quality criteria + examples + pitfalls

**Where to save:** `/skills/skill-name/SKILL.md` with `type: component` in frontmatter

---

### **Interactive Skills** (Guided Discovery)
**Use when:** You need adaptive questioning that gathers context and offers recommendations.

**Examples:**
- "Which prioritization framework should I use?" (asks about stage, data, constraints → recommends RICE/ICE/Kano)
- "Help me prep discovery interviews" (asks about research goals → generates interview guide)

**Structure:**
- Asks 3-5 adaptive questions
- Offers 3-5 numbered options based on context
- Allows user to pick by number or provide custom input
- Applies component skills at the end

**Where to save:** `/skills/skill-name/SKILL.md` with `type: interactive` in frontmatter

---

### **Workflow Skills** (End-to-End Processes)
**Use when:** You need a complete PM process that orchestrates multiple skills.

**Examples:**
- Product strategy session (positioning → problem framing → roadmap)
- Discovery process (frame problem → research → validate solutions)
- PRD development (problem statement → solution → user stories)

**Structure:**
- Multi-phase process (typically 4-8 phases)
- References component and interactive skills
- Includes decision points ("If X, then do Y")

**Where to save:** `/skills/skill-name/SKILL.md` with `type: workflow` in frontmatter

---

## 📐 Skill Format (Required Structure)

### Naming Conventions

Skill names must be **generic and universal** — they describe what the skill does, not who built it. No contributor handles, company names, or personal prefixes.

- ✅ `pm-skill-creator`
- ✅ `discovery-interview-prep`
- ❌ `acme-pm-skill-creator`
- ❌ `yourhandle-discovery-prep`

The skill belongs to the community once merged. The name should reflect that.

Every skill **must** follow this format:

~~~markdown
---
name: skill-name
description: Brief one-line description of what this skill does (≤ 200 chars for Claude web uploads)
type: component
---

## Purpose
One paragraph: What this skill does and when to use it.
(Make it outcome-focused: "build a roadmap that survives exec review," not "learn about roadmaps")

## Key Concepts
Core frameworks, definitions, mental models.
- Use bullets or tables
- Define PM jargon (don't assume everyone knows "JTBD" or "RICE")
- Include "Anti-Patterns" (what this is NOT)

## Application
Step-by-step guidance.
- Write as instructions anyone can follow
- Use numbered steps when sequence matters
- Call out decision points ("If X, do Y; if Z, do Q")
- **For component skills:** Focus on template + quality criteria
- **For interactive skills:** Map question sequence with numbered options
- **For workflow skills:** Show phases with decision branches

## Examples
Real-world cases showing the skill in action.
- Show both "good" and "bad" examples
- Make examples specific, not generic ("SaaS onboarding," not "product feature")
- **For interactive skills:** Show sample conversation flows

## Common Pitfalls
What to avoid and why.
- Name the failure mode ("Solution-First Thinking")
- Explain the consequence ("Build wrong thing, waste time")
- Provide the fix ("Frame problem first with customer evidence")

## References
- Related skills (link to component/interactive/workflow skills this uses or is used by)
- External frameworks (cite sources: Jeff Patton, Teresa Torres, etc.)
- Original authors/books
~~~

**Non-negotiable sections:**
- Purpose
- Key Concepts
- Application
- Examples
- Common Pitfalls
- References

**Optional sections:**
- Decision trees
- Templates
- Checklists

---

## ✅ Quality Checklist (Before Submitting)

Your skill should pass these checks:

- [ ] **Pedagogic:** Does it explain the *why*, not just the *what*? Would a PM finish this knowing more than when they started?
- [ ] **Agent-ready:** Could an AI read this and apply it without asking clarifying questions?
- [ ] **Self-contained:** Does it define its own terms? (No unexplained jargon)
- [ ] **Practical:** Does it include at least one concrete example?
- [ ] **Opinionated:** Does it take a stance? (Not just "here are options")
- [ ] **Skimmable:** Can you skim the headings and bullets and get 80% of the value?
- [ ] **Zero fluff:** Did you cut every word that doesn't earn its keep? (But not the lesson — see Design Philosophy above)
- [ ] **Properly categorized:** Is it clearly a component, interactive, or workflow skill?
- [ ] **If you removed existing content:** Can you confirm nothing pedagogic was lost? "Why This Works," Anti-Patterns, consequence explanations in Common Pitfalls, and educational preambles are load-bearing. "The agent already knows this" is not a valid reason to remove them — the human reader may not.

**For Interactive Skills Only:**
- [ ] **Bounded questions:** 3-5 questions max (not a 20-question survey)
- [ ] **Enumerated options:** 3-5 numbered choices per question
- [ ] **Context-aware:** Options adapt based on previous answers
- [ ] **Handles input gracefully:** User can pick numbers, combine options, or provide custom input

---

## 🎨 Writing Style Guide

### ✅ Do This:
- Write like you're teaching a smart colleague (not a junior intern)
- Use short sentences and active voice
- Name tradeoffs (not just "best practices")
- Include vivid labels when helpful ("feature factory," "HiPPO decision-making")
- Make it copy/paste ready for AI agents
- Show real examples (anonymize if needed)

### ❌ Don't Do This:
- Use filler phrases ("Well, let's explore..." / "It's important to note...")
- Moralize or preach ("You MUST always..." / "It's critical that...")
- Hedge excessively ("This might potentially help in some cases...")
- Write academic essays (this isn't a journal article)
- Assume everyone has context (define terms, explain frameworks)
- Dump 10 questions at once (interactive skills ask 3-5 max)

**Tone:** Professional but conversational. Clear over clever.

---

## 🔄 Review Process

**A note on external scoring tools:**
Tools that score or grade skills can be useful for surfacing structural issues. If you use one, share the results — that's helpful context. Just note that most tools optimize for agent execution efficiency, which is only half this repo's mission. A score improvement that comes from removing pedagogic content will be sent back for revision.

**What happens after you submit:**

1. **We review within 7 days**
   - Check quality (does it pass the checklist?)
   - Check fit (does it align with repository goals?)
   - Check clarity (can AI and PMs both follow it?)

2. **We provide feedback**
   - If approved: Merge and publish
   - If changes needed: Suggest edits
   - If not a fit: Explain why (and suggest alternatives)

3. **You get credit**
   - Your name in the skill file
   - Mentioned in release notes
   - Added to contributors list

---

## 🙏 What We're Looking For

**High-priority contributions:**
- **Missing PM frameworks** (OKRs, go-to-market planning, feature launches, A/B testing)
- **Better examples** (especially "bad" examples showing common mistakes)
- **Clearer instructions** (where existing skills are confusing)

**Medium-priority:**
- Additional references to external frameworks
- Cross-references between related skills
- Alternative approaches (e.g., different prioritization frameworks)

**Low-priority:**
- Reformatting (skills already follow standard format)
- Style tweaks (unless clarity is significantly improved)

---

## 🚫 What We Won't Accept

**Out of scope:**
- Company-specific processes (skills should be universal)
- Generic advice ("communicate with stakeholders") without a specific framework
- Duplicate content (check existing skills first)
- Sales or marketing content (this is a PM skill library)
- Overly academic or theoretical frameworks (skills must be actionable)
- **Efficiency edits that strip pedagogic value** — trimming explanation, removing anti-patterns, or cutting examples to make a skill shorter is a defect. The teaching is the point. Specifically protected: "Why This Works" sections, Anti-Patterns, consequence chains in Common Pitfalls, and educational preambles that explain why a framework exists.
- **Content removal justified only by a score from an external tool** — external skill scoring tools may optimize for agent execution efficiency, which is only half this repo's mission. Score improvements are useful signal, but content removal requires explicit justification beyond a score change.

---

## 💬 Questions?

**Not sure if your idea fits?**
- Open an issue and describe it
- We'll let you know if it's a good candidate

**Need help formatting?**
- Submit a rough draft
- We'll help you polish it

**Want to brainstorm?**
- Reach out to Dean on [LinkedIn](https://linkedin.com/in/deanpeters)

---

## 📜 License Note

By contributing, you agree that your contributions will be licensed under the CC BY-NC-SA 4.0 license (same as this repository).

---

**Thank you for making Product Manager Skills better!** 🙏

Every contribution helps PMs around the world work smarter with AI.
