USP

Unlike generic AI prompts, this artifact provides 40 structured, best-practice PM skills, complete with templates and workflows, ensuring high-quality, consistent outputs across the entire product lifecycle. It's designed for immediate int…

Use cases

• 01Deeply understanding customer motivations (JTBD)
• 02Outcome-driven product discovery and prioritization (Opportunity Solution Tree)
• 03Framing new initiatives and communicating product strategy (Problem Statement)
• 04Keeping local pm-skills installation up to date
• 05Generating consistent, professional product management outputs

Detected files (9)

• docs/templates/skill-template/SKILL.mdskill
  Show content (1550 bytes)

  ---
  name: <phase-or-classification-skill-name>
  description: <single-line 20-100 word description; include trigger keywords and do not use folded YAML>
  phase: <discover|define|develop|deliver|measure|iterate>
  # classification: <foundation|utility>   # For non-domain skills, use classification and omit phase
  version: "1.0.0"
  updated: <YYYY-MM-DD>
  license: Apache-2.0
  metadata:
    category: <one of: research, problem-framing, ideation, specification, validation, reflection, coordination>
    frameworks: [triple-diamond, lean-startup, design-thinking]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  
  # <Skill Title>
  
  <One paragraph overview of what this skill produces and why it matters.>
  
  ## When to Use
  
  - <Situation 1>
  - <Situation 2>
  - <Situation 3>
  
  ## When NOT to Use (Optional)
  
  - <Common misuse to avoid>
  - <When another skill is a better fit>
  
  ## Instructions
  
  When asked to <create artifact>, follow these steps:
  
  1. **<Step 1 Title>**
     <What to do and why>
  
  2. **<Step 2 Title>**
     <What to do and why>
  
  3. **<Step 3 Title>**
     <What to do and why>
  
  4. **<Step 4 Title>**
     <What to do and why>
  
  ## Output Contract
  
  Use `references/TEMPLATE.md` as the output format. A complete response should:
  
  - <Required element 1>
  - <Required element 2>
  - <Required element 3>
  
  ## Quality Checklist
  
  Before finalizing, verify:
  
  - [ ] <Quality criterion 1>
  - [ ] <Quality criterion 2>
  - [ ] <Quality criterion 3>
  
  ## Examples
  
  See `references/EXAMPLE.md` for a completed example.
  

• skills/define-jtbd-canvas/SKILL.mdskill
  Show content (3485 bytes)

  ---
  name: define-jtbd-canvas
  description: Creates a Jobs to be Done canvas capturing the functional, emotional, and social dimensions of a customer job. Use when deeply understanding customer motivations, designing for jobs, or reframing product positioning.
  phase: define
  version: "2.0.0"
  updated: 2026-01-26
  license: Apache-2.0
  metadata:
    category: problem-framing
    frameworks: [triple-diamond, lean-startup, design-thinking]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  # Jobs to be Done Canvas
  
  A Jobs to be Done (JTBD) canvas captures the complete picture of why customers "hire" products to make progress in their lives. Based on Clayton Christensen's framework, JTBD goes beyond features and demographics to understand the underlying motivations.functional, emotional, and social.that drive customer behavior.
  
  ## When to Use
  
  - When deeply researching customer motivations before building
  - To reframe product positioning around customer progress
  - When existing personas feel too surface-level or demographic
  - During competitive analysis to identify why customers switch
  - When designing marketing messages that resonate
  - To align team on who the customer really is and what they need
  
  ## Instructions
  
  When asked to create a JTBD canvas, follow these steps:
  
  1. **Identify the Job Performer**
     Define who is doing this job. Go beyond demographics to capture the circumstance they're in. The same person can have different jobs in different situations.
  
  2. **Articulate the Circumstance**
     Describe when and where this job arises. Jobs are triggered by specific situations. Understanding context helps predict when customers will seek a solution.
  
  3. **Write the Job Statement**
     Use the format: "When [situation], I want to [motivation], so I can [desired outcome]." The job statement captures the core progress the customer seeks.
  
  4. **Define the Functional Job**
     What is the practical task the customer needs to accomplish? This is the tangible, measurable part of the job. Be specific about what "done" looks like.
  
  5. **Capture the Emotional Job**
     How does the customer want to feel during and after the job? Emotional jobs often drive decisions more than functional ones. Include both desired feelings and feelings to avoid.
  
  6. **Identify the Social Job**
     How does the customer want to be perceived by others? Social jobs relate to status, identity, and relationships. Not all jobs have strong social dimensions.
  
  7. **Map Competing Solutions**
     What are customers currently "hiring" to do this job? Include direct competitors, indirect alternatives, and non-consumption (doing nothing). Understanding current solutions reveals what to compete against.
  
  8. **Define Hiring Criteria**
     What makes customers choose one solution over another? What are the "must haves" vs. "nice to haves"? This informs positioning and prioritization.
  
  ## Output Format
  
  Use the template in `references/TEMPLATE.md` to structure the output.
  
  ## Quality Checklist
  
  Before finalizing, verify:
  
  - [ ] Job statement follows "When... I want... so I can..." format
  - [ ] Circumstance is specific (not just "anytime")
  - [ ] Functional job describes tangible outcome
  - [ ] Emotional job includes how customer wants to feel
  - [ ] Competing solutions include non-obvious alternatives
  - [ ] Insights are based on research, not assumptions
  
  ## Examples
  
  See `references/EXAMPLE.md` for a completed example.
  

• skills/define-opportunity-tree/SKILL.mdskill
  Show content (3514 bytes)

  ---
  name: define-opportunity-tree
  description: Creates an opportunity solution tree mapping desired outcomes to opportunities and potential solutions. Use for outcome-driven product discovery, prioritization, or communicating product strategy.
  phase: define
  version: "2.0.0"
  updated: 2026-01-26
  license: Apache-2.0
  metadata:
    category: problem-framing
    frameworks: [triple-diamond, lean-startup, design-thinking]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  # Opportunity Solution Tree
  
  An Opportunity Solution Tree (OST) is a visual framework for product discovery that connects business outcomes to customer opportunities and potential solutions. Developed by Teresa Torres, it prevents the common trap of jumping straight to solutions by ensuring every feature idea traces back to a customer need and measurable outcome.
  
  ## When to Use
  
  - During continuous product discovery to organize learning
  - When prioritizing what opportunities to pursue
  - To communicate product strategy to stakeholders
  - When you have too many feature ideas and need structure
  - After user research to connect insights to action
  - When aligning team on what outcomes matter most
  
  ## Instructions
  
  When asked to create an opportunity solution tree, follow these steps:
  
  1. **Define the Desired Outcome**
     Start at the top with a clear, measurable business or product outcome. This should be something you can influence through product changes. Express it quantitatively when possible (e.g., "Increase 30-day retention from 40% to 55%").
  
  2. **Identify Opportunity Areas**
     Branch out to 3-5 opportunity areas.places where customer needs or pain points could be addressed. Opportunities are not solutions; they're customer problems, needs, or desires. Phrase them from the customer's perspective.
  
  3. **Add Supporting Evidence**
     For each opportunity, note the evidence that supports it: user research quotes, behavioral data, support tickets, or market trends. Strong opportunities have multiple evidence sources.
  
  4. **Brainstorm Solutions**
     For each opportunity, generate 2-4 potential solutions. Don't self-censor at this stage. Solutions can range from quick experiments to major features. Keep them specific enough to evaluate.
  
  5. **Define Assumption Tests**
     For each promising solution, identify the riskiest assumption and design a lightweight experiment to test it. Good tests validate whether the solution will actually address the opportunity.
  
  6. **Prioritize the Tree**
     Not all branches are equal. Mark which opportunity and solution you'll pursue first based on potential impact, confidence, and effort. The tree is a living document.you'll iterate as you learn.
  
  7. **Visualize the Structure**
     Create a tree diagram showing the hierarchy: outcome at top, opportunities below, solutions beneath each opportunity, and experiments at the leaves.
  
  ## Output Format
  
  Use the template in `references/TEMPLATE.md` to structure the output.
  
  ## Quality Checklist
  
  Before finalizing, verify:
  
  - [ ] Outcome is measurable and within product team's influence
  - [ ] Opportunities are customer-centric (needs/problems, not features)
  - [ ] Each opportunity has supporting evidence documented
  - [ ] Multiple solutions exist per opportunity (not jumping to one)
  - [ ] Assumptions are explicit and experiments designed
  - [ ] Prioritization is clear (which branch to explore first)
  
  ## Examples
  
  See `references/EXAMPLE.md` for a completed example.
  

• skills/define-problem-statement/SKILL.mdskill
  Show content (3125 bytes)

  ---
  name: define-problem-statement
  description: Creates a clear problem framing document with user impact, business context, and success criteria. Use when starting a new initiative, realigning a drifted project, or communicating up to leadership.
  phase: define
  version: "2.0.0"
  updated: 2026-01-26
  license: Apache-2.0
  metadata:
    category: problem-framing
    frameworks: [triple-diamond, lean-startup, design-thinking]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  # Problem Statement
  
  A problem statement is a concise document that frames the problem you're solving, articulates the impact on users and the business, and defines clear success criteria. It serves as the foundation for all subsequent product work by ensuring alignment on *what* problem to solve before jumping to *how* to solve it.
  
  ## When to Use
  
  - Starting a new initiative or project to establish shared understanding
  - Realigning a drifted project back to its original intent
  - Communicating up to leadership or stakeholders about priorities
  - Evaluating whether a proposed solution actually addresses the core problem
  - Onboarding new team members to provide context
  
  ## Instructions
  
  When asked to create a problem statement, follow these steps:
  
  1. **Identify the User Segment**
     Ask who is experiencing this problem. Get specific about the user persona, role, or segment. Avoid vague descriptions like "users" . instead target "mobile shoppers completing checkout" or "enterprise admins managing 50+ users."
  
  2. **Understand the Pain Points**
     Explore what friction, frustration, or unmet need the user experiences. Ask probing questions to understand the severity and frequency of the problem. Look for evidence from user research, support tickets, or behavioral data.
  
  3. **Establish Business Context**
     Connect the user problem to business impact. How does this problem affect revenue, retention, growth, or strategic goals? Why should the organization invest in solving this now versus later?
  
  4. **Define Success Metrics**
     Identify how you will measure success. What metrics will move if this problem is solved? Establish current baselines and target improvements. Be specific and time-bound.
  
  5. **Surface Constraints and Considerations**
     Note any technical limitations, resource constraints, regulatory requirements, or dependencies that will shape the solution space.
  
  6. **Capture Open Questions**
     Document what you don't know yet. What assumptions need validation? What additional research is needed?
  
  ## Output Format
  
  Use the template in `references/TEMPLATE.md` to structure the output.
  
  ## Quality Checklist
  
  Before finalizing, verify:
  
  - [ ] Problem is specific to a defined user segment (not "all users")
  - [ ] Impact is quantified with data or reasonable estimates
  - [ ] Success metrics have baselines and targets
  - [ ] Problem describes the "what" without prescribing the "how"
  - [ ] Business context explains why this matters now
  - [ ] Open questions are captured for follow-up
  
  ## Examples
  
  See `references/EXAMPLE.md` for a completed example.
  

• docs/internal/efforts/F-24-update-pm-skills/drafts/skills/utility-update-pm-skills/SKILL.mdskill
  Show content (14017 bytes)

  ---
  name: utility-update-pm-skills
  description: >-
    Checks for newer pm-skills releases, compares local vs. latest version,
    previews what would change, and updates local files after user confirmation.
    Generates a structured update report documenting changed files, new
    capabilities, and the value delta between versions. Use when you want to
    bring a local pm-skills installation up to date.
  classification: utility
  version: "1.0.0"
  updated: 2026-04-09
  license: Apache-2.0
  metadata:
    category: coordination
    frameworks: [triple-diamond]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  
  # PM Skills Updater
  
  This skill updates a local pm-skills installation to the latest public
  release. It validates connectivity, compares versions, previews changes,
  and produces a structured report documenting what was updated and what
  new capabilities are available.
  
  ## When to Use
  
  - When you want to update local pm-skills to the latest release
  - When you want to check if a newer version is available
  - After a new pm-skills release is announced
  - When onboarding and you want to confirm you have the latest version
  
  ## When NOT to Use
  
  - To create or edit individual skills -> use `/pm-skill-builder` or `/pm-skill-iterate`
  - To validate skills against conventions -> use `/pm-skill-validate`
  - If you are a maintainer working directly on the pm-skills repo (use git)
  - To pin a specific older version (this skill always targets the latest release)
  
  ## Flags
  
  | Flag | Behavior |
  |------|----------|
  | *(none)* | Full update flow: pre-flight → preview → confirm → update → report |
  | `--report-only` | Pre-flight → preview → report (no files written) |
  | `--status` | Lightweight version check . prints current and latest version, then stops |
  
  ### --status behavior
  
  When `--status` is provided, run only the pre-flight checks and display:
  
  ```
  pm-skills v{local} (installed, from {source})
  pm-skills v{latest} (latest, released {date})
  {Status: up to date | update available ({type})}
  
  Run /update-pm-skills for details, or /update-pm-skills --report-only for a preview.
  ```
  
  No report file is generated. No files are written.
  
  ## Instructions
  
  When asked to update pm-skills (without `--status`), follow these steps:
  
  ### Step 1: Pre-Flight
  
  Run three checks before proceeding:
  
  1. **Network access**: Reach the GitHub API or repository URL
     (`https://github.com/product-on-purpose/pm-skills`). Use any
     available method: `curl`, `wget`, GitHub CLI (`gh`), or MCP tools.
  
  2. **Latest version**: Query the latest release using this fallback chain
     (try each in order, use the first that succeeds):
     1. GitHub API: `GET /repos/product-on-purpose/pm-skills/releases/latest`
     2. GitHub CLI: `gh release list --repo product-on-purpose/pm-skills --limit 1`
     3. Git: `git ls-remote --tags https://github.com/product-on-purpose/pm-skills.git`
  
     If all three fail (rate limiting, 404, malformed response, no network),
     enter degraded mode (see below).
  
     Record: version string, release date, release notes URL, release notes body.
  
  3. **Local version**: Read from the first available source:
     - `.claude-plugin/plugin.json` → `version` field
     - `marketplace.json` → `plugins[0].version` field
     - `CHANGELOG.md` → most recent version header
     - Git tags → most recent `v*` tag
  
     **Version parsing:** Normalize by stripping an optional `v` prefix and
     trimming whitespace. If a source is present but yields an empty,
     non-semver, or malformed string (invalid JSON, missing field), skip it
     with a warning and try the next source. Only fall back to `0.0.0`
     after all four sources fail.
  
  **If network access fails** (degraded mode):
  - Report the failure with error details.
  - Provide manual update instructions:
    > Visit https://github.com/product-on-purpose/pm-skills/releases to
    > download the latest release. Extract the archive and copy the
    > `skills/`, `commands/`, `_workflows/`, and other content directories
    > to your local pm-skills installation.
  - Stop execution.
  
  ### Step 2: Version Comparison
  
  Compare the local version against the latest release using semver.
  
  **If local version >= latest version:**
  - Report: "Your pm-skills installation is up to date (v{local})."
  - Offer to generate a report-only anyway.
  - Stop execution.
  
  **If local version < latest version:**
  - Show the version delta:
    ```
    Local version:  v{local}
    Latest version: v{latest}
    Update type:    {major | minor | patch}
    ```
  - **Major version warning**: If the update is a major bump (e.g., v2.x
    to v3.x), show a prominent warning:
    > This is a major version update. It may include breaking changes to
    > skill contracts. Review the release notes before proceeding.
  - Continue to Step 3.
  
  ### Step 3: Preview
  
  Show the user what the update includes:
  
  1. **Version delta**: local version, latest version, update type.
  
  2. **Value summary**: Derive from CHANGELOG entries between the two
     versions, GitHub release notes, and directory diffs (new skills/,
     new _workflows/ files):
     - New skills and what they enable
     - Updated skills and what improved
     - New workflows and what they connect
     - Other notable changes
  
  3. **File manifest**: List of files and folders that will be written,
     grouped by directory with counts:
     ```
     Files to be written:
       skills/       31 files (2 new, 29 updated)
       commands/     38 files (2 new, 36 updated)
       _workflows/    9 files (1 new, 8 updated)
       other          7 files
       Total:        85 files
     ```
  
  **If `--report-only`:** Generate the report using `references/TEMPLATE.md`
  with the banner "Report only . update was not applied." Save to
  `_pm-skills/updates/update-report_v{latest}_report-only_{YYYY-MM-DD_HHMMSS}.md`. Stop
  execution.
  
  ### Step 4: Confirmation
  
  Prompt the user for two decisions:
  
  1. **Update confirmation**:
     "These files will be overwritten. Proceed? [yes / no]"
     - If major version bump: require typing "yes" explicitly.
     - If the user declines: save a report-only and stop.
  
  2. **Backup offer**:
     "Create a backup of current files before updating?
     [yes (recommended) / no]"
     - If yes: copy all in-scope files to
       `_pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/`
     - Create the `_pm-skills/` directory if it doesn't exist.
  
  ### Step 5: Update
  
  Execute the update using validated-before-copy with backup:
  
  1. **Download**: Fetch the release ZIP asset (`pm-skills-vX.Y.Z.zip`)
     from the GitHub Release page to a temporary directory. This is the
     curated build artifact produced by `build-release.sh` . it includes
     only user-facing content and excludes `docs/internal/`.
  
  2. **Validate**: Confirm the extracted archive contains `skills/`,
     `commands/`, `AGENTS.md`, and `.claude-plugin/plugin.json`. If
     validation fails, report the error and stop without writing any files.
  
  3. **Copy**: Overwrite in-scope files from the extracted archive to the
     install root. Show progress per directory:
     ```
     Updating pm-skills v2.9.0 -> v2.10.0...
       skills/       31/31 ████████████████████  done
       commands/     38/38 ████████████████████  done
       _workflows/    9/9  ████████████████████  done
       other files    7/7  ████████████████████  done
     ```
  
  4. **Clean up**: Remove the temporary directory.
  
  ### Step 6: Post-Update
  
  1. **Smoke test**:
     - Version consistency: `plugin.json`, `marketplace.json`, and
       `CHANGELOG.md` all reflect the new version. (Note: version detection
       in Step 1 uses first-match; the smoke test verifies all sources
       agree. A mismatch here suggests a release packaging issue.)
     - File integrity: `AGENTS.md`, `skills/`, `commands/`, `_workflows/`
       all exist.
     - Skill count delta: count skills before and after, report the change.
     - If any check fails: warn the user with specific details. Do NOT
       auto-rollback. Provide recovery guidance:
       - **Version mismatch**: "Run the update again, or manually edit
         {file} to set the version to {expected}."
       - **Missing files**: "Re-run `/update-pm-skills` to re-download,
         or restore from backup: `cp -r _pm-skills/backups/{dir}/* .`"
       - **If backup exists**: Always remind the user of the backup
         location and restore command.
  
  2. **Summary line**: Show a single scannable confirmation:
     ```
     Updated v{old} -> v{new} | +{n} skills, +{n} workflows | Report: _pm-skills/updates/{file}
     ```
  
  3. **Completion report**: Generate using `references/TEMPLATE.md` and
     save to `_pm-skills/updates/update-report_v{from}-to-v{to}_{YYYY-MM-DD_HHMMSS}.md`
  
  4. **MCP advisory**: If `../pm-skills-mcp/` exists, try to read
     `pm-skills-source.json`. If the file is missing or malformed, show:
     "pm-skills-mcp detected but pm-skills-source.json not found or
     unreadable. Check the MCP repo manually." If readable, show:
     ```
     pm-skills-mcp detected at ../pm-skills-mcp/
       Embedded skills version: v{embedded}
       Updated pm-skills version: v{new}
  
       To update the MCP server's embedded skills:
         cd ../pm-skills-mcp && npm run embed-skills && npm run build
     ```
  
  5. **Next steps**:
     ```
     Next Steps:
     - Review the update report at _pm-skills/updates/{report-file}
     - Run /pm-skill-validate --all to verify skill integrity
     - Run local CI: bash scripts/lint-skills-frontmatter.sh
     - Check release notes: {release-url}
     ```
  
  ## File Scope
  
  The updater writes only files present in the release ZIP asset
  (`pm-skills-vX.Y.Z.zip`), which is the curated build produced by
  `build-release.sh`. The ZIP excludes `docs/internal/` and other
  non-user-facing content . no exclusion logic is needed at copy time.
  
  **Files included in the release ZIP (updated):**
  
  | Path | Rationale |
  |------|-----------|
  | `skills/` | Core skill files |
  | `commands/` | Slash command definitions |
  | `_workflows/` | Workflow chains |
  | `library/` | Sample library and skill output samples (note: user-added samples may be overwritten) |
  | `AGENTS.md` | Skill discovery for IDEs |
  | `.claude-plugin/plugin.json` | Version + plugin metadata |
  | `marketplace.json` | Marketplace metadata |
  | `CHANGELOG.md` | Release history |
  | `README.md` | Public docs |
  | `docs/` (public guides, reference, workflows) | User-facing documentation |
  | `scripts/` | CI/validation scripts |
  | `mkdocs.yml` | Docs site config |
  
  **Files NOT in the release ZIP (never overwritten):**
  
  | Path | Rationale |
  |------|-----------|
  | `docs/internal/` | Excluded from ZIP by `build-release.sh` |
  | `_NOTES/` | Local-only, gitignored, not in ZIP |
  | `_pm-skills/` | Local state (reports, backups), not in ZIP |
  | `.github/` | CI workflows, not in ZIP |
  | `CONTRIBUTING.md`, `LICENSE` | Not in ZIP (repo-level files) |
  
  ## Output Contract
  
  The skill MUST:
  - Validate network access before any remote operations
  - Show a preview before writing any files
  - Require explicit user confirmation before overwriting
  - Offer a backup before overwriting
  - Use validated-before-copy (download to temp, validate, then copy; backup is the recovery path for mid-copy failures)
  - Generate a report in both modes (report-only and completion)
  - Run the post-update smoke test
  - Show MCP advisory if sibling repo is detected
  
  The skill MUST NOT:
  - Write files without user confirmation
  - Proceed without network access confirmation
  - Modify files outside the pm-skills directory
  - Modify `docs/internal/`, `_NOTES/`, or `_pm-skills/` with upstream content
  - Auto-rollback on smoke test failure (inform the user instead)
  - Delete local files that don't exist in the upstream release
  
  ## Quality Checklist
  
  Before marking the update complete, verify:
  
  - [ ] Pre-flight passed: network, versions detected
  - [ ] User was shown preview before any files were written
  - [ ] User explicitly confirmed before update proceeded
  - [ ] Backup was offered (and created if accepted)
  - [ ] Archive was downloaded to temp and validated before copying
  - [ ] All in-scope files were written successfully
  - [ ] Version consistency: plugin.json, marketplace.json, CHANGELOG match
  - [ ] File integrity: AGENTS.md, skills/, commands/, _workflows/ exist
  - [ ] Skill count delta is reported (before -> after)
  - [ ] Report was generated and saved to `_pm-skills/updates/`
  - [ ] MCP advisory was shown if sibling repo detected
  - [ ] Next steps were presented
  - [ ] Summary line displayed
  
  ## FAQ
  
  **I'm a contributor who cloned the repo. Should I use this skill?**
  No. Use `git pull` or `git fetch && git merge` instead. This skill is
  for end users who installed pm-skills as a plugin or downloaded a release.
  
  **Can I update to a specific version instead of the latest?**
  Not in v1. This skill always targets the latest release. To install a
  specific version, download it manually from the releases page.
  
  **What happens to my local notes and planning docs?**
  They are never touched. The skill explicitly excludes `docs/internal/`,
  `_NOTES/`, and `_pm-skills/` from updates. See the File Scope table.
  
  **What happens to files I added that aren't in the upstream release?**
  They are left untouched. The skill only overwrites files that exist in
  the new release . it never deletes local files.
  
  **How do I undo an update?**
  If you created a backup (the default offer), restore it:
  `cp -r _pm-skills/backups/v{version}_{timestamp}/* .`
  If you didn't create a backup but have git, use `git checkout .` to
  restore tracked files to their last committed state.
  
  **The update failed partway through. What do I do?**
  The skill validates before copying (download to temp, check, then write),
  so partial failures are rare. If it does happen: restore from backup if
  available, or re-run `/update-pm-skills` to retry.
  
  ## Further Reading
  
  For a visual walkthrough and additional context, see the
  [Updating PM Skills Guide](../../docs/guides/updating-pm-skills.md).
  

• skills/define-hypothesis/SKILL.mdskill
  Show content (3067 bytes)

  ---
  name: define-hypothesis
  description: Defines a testable hypothesis with clear success metrics and validation approach. Use when forming assumptions to test, designing experiments, or aligning team on what success looks like.
  phase: define
  version: "2.0.0"
  updated: 2026-01-26
  license: Apache-2.0
  metadata:
    category: ideation
    frameworks: [triple-diamond, lean-startup, design-thinking]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  # Hypothesis
  
  A hypothesis is a testable prediction about how a change will affect user behavior or business outcomes. It transforms assumptions into explicit statements that can be validated or invalidated through experimentation. Well-formed hypotheses prevent teams from building features based on untested beliefs and create shared understanding of what success looks like.
  
  ## When to Use
  
  - After problem framing, before committing to a solution
  - When designing experiments or A/B tests
  - When team members have differing assumptions about user behavior
  - Before investing significant engineering resources in a feature
  - When pivoting direction and need to validate the new approach
  
  ## Instructions
  
  When asked to create a hypothesis, follow these steps:
  
  1. **State the Belief**
     Articulate what you believe will happen. Use the structured format: "We believe that [action/change] for [target user] will [expected outcome]." Be specific about the intervention . vague hypotheses can't be tested.
  
  2. **Identify the Target User**
     Define who this hypothesis applies to. A hypothesis about "users" is too broad. Specify the segment: new users in their first week, power users with 10+ sessions, churned users returning, etc.
  
  3. **Define the Expected Outcome**
     What behavior change or result do you expect? Frame it in terms of user actions (complete onboarding, make a purchase, return within 7 days) rather than internal metrics when possible.
  
  4. **Set Success Metrics**
     Choose a primary metric that directly measures the expected outcome. Include secondary metrics that provide context and guardrail metrics that ensure you're not causing harm elsewhere.
  
  5. **Describe Validation Approach**
     How will you test this hypothesis? A/B test, user interviews, prototype testing, cohort analysis? Be specific about sample size, duration, and statistical requirements.
  
  6. **Document Risks and Assumptions**
     What could invalidate this hypothesis beyond the test results? What are you assuming to be true that you haven't validated?
  
  ## Output Format
  
  Use the template in `references/TEMPLATE.md` to structure the output.
  
  ## Quality Checklist
  
  Before finalizing, verify:
  
  - [ ] Hypothesis is falsifiable (possible to prove wrong)
  - [ ] Success metric has a specific numeric target
  - [ ] Target user segment is clearly defined
  - [ ] Validation approach is practical and time-bound
  - [ ] Pass/fail criteria are unambiguous
  - [ ] Hypothesis doesn't assume the solution works
  
  ## Examples
  
  See `references/EXAMPLE.md` for a completed example.
  

• docs/internal/efforts/F-24-update-pm-skills/_discovery/2026-04-09_claude-web-session/skills/utility-update-pm-skills/SKILL.mdskill
  Show content (12535 bytes)

  ---
  name: utility-update-pm-skills
  description: Validates internet access, compares the locally installed pm-skills version against the latest public release, and updates local files with conflict-aware overwrite-or-skip options. Produces an update report listing changed files, skipped files, and new capabilities. Use when you want to bring a local pm-skills installation up to date.
  classification: utility
  version: "1.0.0"
  updated: 2026-04-09
  license: Apache-2.0
  metadata:
    category: coordination
    frameworks: [triple-diamond]
    author: product-on-purpose
  ---
  <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
  
  # PM Skills Updater
  
  This skill updates a local pm-skills installation to the latest public
  release. It validates connectivity, compares versions, detects local
  modifications, gives the user control over conflict resolution, and
  produces a structured update report documenting every change.
  
  The updater operates in three phases:
  - **Pre-flight** -- validate internet access and determine version delta.
  - **Update** -- fetch the latest release and apply changes with
    conflict-aware overwrite-or-skip logic.
  - **Report** -- generate a markdown report summarizing what changed,
    what was skipped, and what new capabilities are available.
  
  ## When to Use
  
  - When you want to update your local pm-skills to the latest release
  - After a new pm-skills version is announced and you want to pull it in
  - When you're unsure whether your local copy is current
  - When onboarding to a team that uses pm-skills and you want the latest version
  - When you want a structured summary of what changed between your version and the latest
  
  ## When NOT to Use
  
  - To create or edit individual skills -> use `/pm-skill-builder` or `/pm-skill-iterate`
  - To validate skills against conventions -> use `/pm-skill-validate`
  - If you are a maintainer working directly on the pm-skills repo (use git instead)
  - If you need to pin a specific older version (this skill always targets the latest release)
  
  ## Instructions
  
  When asked to update pm-skills, follow these steps:
  
  ### Step 1: Validate Internet Access
  
  Before attempting any remote operations, confirm connectivity to GitHub.
  
  **How to validate:**
  1. Attempt to reach the GitHub API or the public repository URL:
     `https://github.com/product-on-purpose/pm-skills`
  2. Use any available method: `curl`, `wget`, `fetch`, GitHub CLI (`gh`),
     or the GitHub MCP tools.
  
  **If connectivity fails:**
  - Report the failure clearly with the error details.
  - Suggest troubleshooting steps: check network, proxy settings, VPN,
    or firewall rules.
  - Stop execution. Do not proceed to Step 2.
  
  **If connectivity succeeds:**
  - Report: "Internet access validated. Connected to GitHub."
  - Proceed to Step 2.
  
  ### Step 2: Determine Local Version
  
  Read the local version from these sources (in priority order):
  
  1. `.claude-plugin/plugin.json` -- `version` field
  2. `marketplace.json` -- `plugins[0].version` field
  3. `CHANGELOG.md` -- most recent version header
  4. Git tags -- most recent `v*` tag
  
  Record:
  - **Local version**: the version string (e.g., `2.8.2`)
  - **Local version source**: which file provided the version
  
  If no version can be determined, warn the user and default to `0.0.0`
  (treat as a fresh install requiring full update).
  
  ### Step 3: Fetch Latest Public Release
  
  Query the public repository for the latest release:
  
  **Methods (try in order):**
  1. GitHub API: `GET /repos/product-on-purpose/pm-skills/releases/latest`
  2. GitHub CLI: `gh release list --repo product-on-purpose/pm-skills --limit 1`
  3. Git: `git ls-remote --tags https://github.com/product-on-purpose/pm-skills.git`
  
  Record:
  - **Latest version**: the version string from the latest release
  - **Release date**: when the release was published
  - **Release notes URL**: link to the release page
  - **Release notes body**: the release description (for capability diff in Step 8)
  
  ### Step 4: Compare Versions
  
  Compare the local version against the latest public version.
  
  **If local version >= latest version:**
  - Report: "Your pm-skills installation is up to date (v{local})."
  - Offer to generate a version report anyway (skip to Step 8 with
    no changes to report).
  - Stop execution unless the user requests a forced update.
  
  **If local version < latest version:**
  - Report the version delta:
    ```
    Local version:  v{local}
    Latest version: v{latest}
    Update type:    {major | minor | patch}
    ```
  - If the update is a **major** version bump, warn:
    "This is a major version update. It may include breaking changes to
    skill contracts. Review the release notes before proceeding."
  - Ask: "Proceed with update? [yes / no]"
  - If no, stop execution.
  
  ### Step 5: Scan for Local Modifications
  
  Before fetching new files, scan the local installation for user
  modifications. This protects customizations from being silently
  overwritten.
  
  **How to detect modifications:**
  
  1. **If the local install is a git repo** (preferred):
     - Run `git status --porcelain` to find uncommitted changes.
     - Run `git diff HEAD` to see the actual modifications.
     - Any file with local changes is flagged as "locally modified."
  
  2. **If the local install is NOT a git repo** (downloaded release):
     - Compare file checksums (SHA-256) against a manifest if available.
     - If no manifest is available, skip modification detection and note
       this limitation in the report.
  
  Record a list of locally modified files with their modification type:
  - `modified` -- content differs from the installed version
  - `added` -- file exists locally but not in the original release
  - `deleted` -- file was removed locally
  
  Present the findings:
  ```
  Locally modified files detected: {n}
  - {status} | {file-path}
  - {status} | {file-path}
  ...
  ```
  
  If no modifications are detected, report: "No local modifications
  detected. Safe to update all files."
  
  ### Step 6: Fetch and Apply Updates
  
  Fetch the latest release content and apply updates file by file.
  
  **Update method (try in order):**
  1. **Git pull/merge** (if local is a git repo):
     - `git fetch origin`
     - `git merge origin/main` (or the tagged release)
     - If merge conflicts arise, handle per the conflict resolution
       rules below.
  
  2. **Release archive download** (if not a git repo):
     - Download the release archive (`.tar.gz` or `.zip`).
     - Extract to a temporary directory.
     - Copy files to the local installation per the rules below.
  
  **File-by-file application rules:**
  
  For each file in the update:
  
  | Local status | Action | User prompt |
  |-------------|--------|-------------|
  | Unmodified | Overwrite silently | None |
  | Locally modified | Prompt user | "File `{path}` has local changes. [overwrite / skip / diff]" |
  | New file (not in local) | Add silently | None |
  | Deleted locally | Prompt user | "File `{path}` was deleted locally but exists in the update. [restore / skip]" |
  
  **Conflict resolution options:**
  - **overwrite**: Replace the local file with the upstream version.
    The original is backed up to `{path}.local-backup` before overwriting.
  - **skip**: Keep the local version. Record as skipped in the report.
  - **diff**: Show a side-by-side or unified diff of the local vs. upstream
    version, then re-prompt with [overwrite / skip].
  - **restore**: Add the file back from the upstream version.
  - **overwrite-all**: Apply overwrite to all remaining conflicts without
    further prompting.
  - **skip-all**: Apply skip to all remaining conflicts without further
    prompting.
  
  ### Step 7: Post-Update Validation
  
  After applying updates, run a quick health check:
  
  1. **Version consistency**: Verify that `.claude-plugin/plugin.json`,
     `marketplace.json`, and `CHANGELOG.md` all reflect the new version.
  2. **File integrity**: Confirm that key files exist:
     - `AGENTS.md`
     - `skills/` directory with expected skill count
     - `commands/` directory
     - `_workflows/` directory
  3. **Skill count delta**: Compare the number of skills before and after
     the update. Report any additions or removals.
  
  If validation fails, warn the user with specific details about what
  looks wrong. Do not roll back automatically -- the user may want to
  investigate.
  
  ### Step 8: Generate Update Report
  
  Produce the update report using the template in
  `references/TEMPLATE.md`. This is the primary output artifact.
  
  The report includes:
  
  1. **Version summary**: local (before) -> latest (after), update type.
  2. **Files changed**: every file that was updated, with a one-line
     summary of what changed.
  3. **Files skipped**: files the user chose to skip due to local
     modifications, with the reason.
  4. **Files added**: new files not present in the previous version.
  5. **Files removed**: files present in the old version but not in the
     new one.
  6. **New capabilities**: skills added, skills updated (with version
     deltas), workflows added, and any breaking changes -- derived from
     release notes and file diff analysis.
  7. **Skipped file recovery**: instructions for how to manually update
     any files that were skipped.
  
  **Report delivery:**
  - Display the report in the conversation.
  - Offer to save it as a file: `updates/update-{from}-to-{to}-{date}.md`
    (e.g., `updates/update-v2.8.2-to-v2.9.0-2026-04-09.md`).
  
  ### Step 9: Present Next Steps
  
  After the update completes, suggest next steps:
  
  ```
  ## Next Steps
  
  - Review the update report for any skipped files
  - Run `/pm-skill-validate --all` to verify skill integrity
  - Run local CI: `bash scripts/lint-skills-frontmatter.sh`
  - Check the release notes for any migration steps: {release-url}
  - If you skipped files with local changes, consider merging manually
  ```
  
  ## Degraded Mode
  
  If running in an environment without direct file system or network
  access (e.g., MCP or embedded environment):
  
  1. **No network access**: Cannot perform the update. Report the
     limitation and provide the user with manual update instructions:
     - Link to the latest release page
     - List the steps to download and extract manually
  2. **No file system access**: Cannot scan for local modifications or
     write updated files. Provide:
     - Version comparison (if the user pastes their local version info)
     - Capability diff from release notes
     - A checklist of files the user should update manually
  3. **Partial access**: Do what you can. Clearly note which steps were
     skipped and why in the report.
  
  ## Output Contract
  
  The updater MUST produce an update report following the format in
  `references/TEMPLATE.md`.
  
  The report:
  - Uses the exact section headings defined in the template
  - Includes version information for both local and upstream
  - Lists every file with its disposition (updated, skipped, added, removed)
  - Describes new capabilities derived from the version delta
  - Provides recovery instructions for any skipped files
  
  The updater MUST:
  - Validate internet access before attempting any remote operations
  - Determine the local version before comparing against upstream
  - Never silently overwrite a locally modified file
  - Back up locally modified files before overwriting (if user chooses overwrite)
  - Present a clear prompt for each conflict with diff capability
  - Support batch conflict resolution (overwrite-all / skip-all)
  - Run post-update validation to confirm a healthy state
  
  The updater MUST NOT:
  - Proceed without internet access confirmation
  - Overwrite locally modified files without user consent
  - Delete local files that don't exist in the upstream release
  - Auto-rollback on validation failure (inform the user instead)
  - Modify files outside the pm-skills directory
  
  ## Quality Checklist
  
  Before delivering the update report, verify:
  
  - [ ] Internet access was validated before any remote operations
  - [ ] Local version was correctly identified from available sources
  - [ ] Latest public version was fetched and compared
  - [ ] User was warned about major version updates (if applicable)
  - [ ] All locally modified files were detected and presented
  - [ ] User was prompted for each file conflict (or batch mode was used)
  - [ ] Backups were created for overwritten locally modified files
  - [ ] Post-update validation passed (or failures were reported)
  - [ ] Update report follows the template format exactly
  - [ ] New capabilities section accurately reflects the version delta
  - [ ] Skipped file recovery instructions are provided
  - [ ] Next steps are presented
  
  ## Examples
  
  See `references/EXAMPLE.md` for a completed update report demonstrating
  a minor version update with local modifications, conflict resolution,
  and new capability discovery.
  

• .claude-plugin/marketplace.jsonmarketplace
  Show content (1128 bytes)

  {
    "name": "pm-skills-marketplace",
    "owner": {
      "name": "product-on-purpose",
      "url": "https://github.com/product-on-purpose"
    },
    "description": "Product Management skills for AI agents",
    "plugins": [
      {
        "name": "pm-skills",
        "description": "40 PM skills covering the full product lifecycle: 26 phase skills, 8 foundation skills (including the v2.12.0 OKR Skills set, the v2.11.0 Meeting Skills Family of 5 cross-cutting skills, lean-canvas, and persona), and 6 utility skills. Includes templates, examples, workflows, thread-aligned samples, and lifecycle tools for creating, validating, and iterating skills. Adds the OKR write-and-score cycle pair in v2.12.0. Follows the agentskills.io specification.",
        "version": "2.13.1",
        "source": "./",
        "author": {
          "name": "product-on-purpose",
          "url": "https://github.com/product-on-purpose"
        },
        "homepage": "https://github.com/product-on-purpose/pm-skills",
        "license": "Apache-2.0",
        "keywords": ["product-management", "pm", "prd", "user-stories", "okrs", "agent-skills", "agentskills-io"]
      }
    ]
  }
  

• marketplace.jsonmarketplace
  Show content (942 bytes)

  {
    "name": "pm-skills-marketplace",
    "description": "Product Management skills for AI agents",
    "plugins": [
      {
        "name": "pm-skills",
        "description": "40 PM skills covering the full product lifecycle: 26 phase skills, 8 foundation skills (including the v2.12.0 OKR Skills set, the v2.11.0 Meeting Skills Family of 5 cross-cutting skills, lean-canvas, and persona), and 6 utility skills. Includes templates, examples, workflows, thread-aligned samples, and lifecycle tools for creating, validating, and iterating skills. Adds the OKR write-and-score cycle pair in v2.12.0. Follows the agentskills.io specification.",
        "version": "2.13.0",
        "source": ".",
        "author": "product-on-purpose",
        "homepage": "https://github.com/product-on-purpose/pm-skills",
        "license": "Apache-2.0",
        "keywords": ["product-management", "pm", "prd", "user-stories", "okrs", "agent-skills", "agentskills-io"]
      }
    ]
  }
  

README

git clone https://github.com/product-on-purpose/pm-skills.git && cd pm-skills

You: "Create a PRD for our new search feature"

AI + PM-Skills: Generates a comprehensive PRD with problem statement,
                success metrics, user stories, scope definition, and
                technical considerations-all in professional format.

flowchart LR
    Create["/pm-skill-builder\nCreate"] --> Validate["/pm-skill-validate\nValidate"]
    Validate --> Decision{Findings?}
    Decision -- "PASS" --> Ship["Ship"]
    Decision -- "WARN / FAIL" --> Iterate["/pm-skill-iterate\nIterate"]
    Iterate --> Validate

# Create a new skill
/pm-skill-builder "A skill for writing stakeholder update emails"

# Validate it meets conventions
/pm-skill-validate stakeholder-update-email

# Fix any findings
/pm-skill-iterate stakeholder-update-email   # paste the validation report

npx skills add product-on-purpose/pm-skills

git clone https://github.com/product-on-purpose/pm-skills.git && cd pm-skills

/plugin marketplace add product-on-purpose/pm-skills
/plugin install pm-skills@pm-skills-marketplace

/plugin marketplace add /path/to/your/local/pm-skills
/plugin install pm-skills@pm-skills-marketplace

npx skills add product-on-purpose/pm-skills

# Clone the repo to get slash commands + everything else
git clone https://github.com/product-on-purpose/pm-skills.git
cd pm-skills

# Use any skill with slash commands
/prd "Search feature for e-commerce platform"
/hypothesis "Will one-page checkout increase conversion?"
/user-stories "Recurring tasks feature from PRD"

./scripts/sync-claude.sh   # macOS/Linux
./scripts/sync-claude.ps1  # Windows

{
  "mcpServers": {
    "pm-skills": {
      "command": "npx",
      "args": ["pm-skills-mcp"]
    }
  }
}

# Clone into your project or as a submodule
git clone https://github.com/product-on-purpose/pm-skills.git

# Or add as submodule
git submodule add https://github.com/product-on-purpose/pm-skills.git

git clone https://github.com/product-on-purpose/pm-skills.git
cd pm-skills

# Clone into your workspace
git clone https://github.com/product-on-purpose/pm-skills.git

npx skills add product-on-purpose/pm-skills

# Works for repos with .claude/skills/ structure (e.g., anthropics/skills)
npm i -g openskills
openskills install anthropics/skills
openskills sync

skills/{phase-skill}/
├── SKILL.md              # Instructions for the AI
└── references/
    ├── TEMPLATE.md       # Output structure
    └── EXAMPLE.md        # Real-world example

/prd "Add real-time collaboration to document editor"

/user-stories "Dark mode feature from PRD.md"

/experiment-design "Test impact of simplified onboarding flow"

/adr "Decision to use PostgreSQL for primary database"

/interview-synthesis "5 customer interviews about payment flows"

/workflow-feature-kickoff "Mobile push notifications"

Build → Measure → Learn cycle with hypothesis, experiments, and pivot decisions

Complete product development across all 6 phases and 26 phase skills

pm-skills/
├── skills/                     # 40 PM skills (26 phase + 8 foundation + 6 utility)
├── commands/                   # Slash commands (47) mapping to skills/workflows
├── _workflows/                 # 9 workflows: feature-kickoff, lean-startup, triple-diamond, and 6 more
├── library/                    # Sample output library (skill-output-samples) and related corpus docs
├── scripts/                    # sync-claude.(sh|ps1), build-release.(sh|ps1), validate-commands.(sh|ps1)
├── .github/                    # CI workflows + automation scripts (validate-mcp-sync)
├── docs/                       # Documentation and guides
│   ├── getting-started/        # Setup guides (index + quickstart)
│   ├── guides/                 # How-to guides (using-skills.md, creating-pm-skills.md, mcp-integration.md)
│   ├── reference/              # Technical specs (categories.md, ecosystem.md, project-structure.md)
│   └── templates/              # Skill template (SKILL.md, TEMPLATE.md, EXAMPLE.md)
├── AGENTS.md                   # Universal agent discovery file
├── CONTRIBUTING.md             # Contribution guidelines
└── CHANGELOG.md                # Version history