{"owner":"phuryn","repo":"pm-skills","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"files":{"CLAUDE.md":"# CLAUDE.md\n\nGuidance for AI agents (Claude Code, Cowork, and others) working in this repository. This file is the single source of truth for how the project is structured and maintained.\n\n## Project Overview\n\n**PM Skills** (`phuryn/pm-skills`) — a marketplace of **9 independent plugins** (68 skills, 42 commands) that bring structured product-management workflows to AI coding assistants. Built for Claude Code and Claude Cowork; the skills are also compatible with other agents (Gemini CLI, Cursor, Codex CLI).\n\nOwner: Paweł Huryn — pawel@productcompass.pm — https://www.productcompass.pm\n\n## Repo Structure\n\n```\npm-skills/                           <- repo root\n├── .claude-plugin/marketplace.json  <- root marketplace manifest (lists all 9 plugins)\n├── .docs/images/                    <- images used by README (webp, gif)\n├── .gitattributes\n├── .gitignore\n├── .github/workflows/               <- CI: tests.yml (every PR/push), tag-on-merge.yml (auto-release)\n├── CHANGELOG.md                     <- release source of truth (new ## vX.Y.Z heading on main = release)\n├── CLAUDE.md                        <- this file (agent guidance, single source of truth)\n├── AGENTS.md                        <- pointer to CLAUDE.md (for non-Claude agents)\n├── CONTRIBUTING.md                  <- contributor guidelines\n├── README.md                        <- public documentation (GitHub)\n├── LICENSE                          <- MIT\n├── validate_plugins.py              <- plugin validator\n├── tests/                           <- unit + docs-consistency tests (unittest)\n└── pm-{name}/                       <- 9 plugin directories\n    ├── .claude-plugin/plugin.json   <- per-plugin manifest\n    ├── skills/{skill}/SKILL.md      <- one folder per skill\n    ├── commands/{command}.md        <- one file per command\n    └── README.md                    <- per-plugin documentation\n```\n\n### The 9 plugins\n\n| Plugin | Focus |\n|--------|-------|\n| `pm-product-discovery` | Ideation, experiments, assumption testing, prioritization, interview synthesis |\n| `pm-product-strategy` | Vision, strategy/lean/business-model canvas, SWOT, PESTLE, Ansoff, Porter, monetization |\n| `pm-execution` | PRDs, OKRs, roadmaps, sprints, pre-mortems, stakeholder maps, user stories, red-teaming |\n| `pm-market-research` | Personas, segmentation, sentiment analysis, competitive analysis, market sizing |\n| `pm-data-analytics` | SQL query generation, cohort/retention analysis |\n| `pm-go-to-market` | GTM strategy, growth loops, motions, beachhead segments, ICPs |\n| `pm-marketing-growth` | Marketing ideas, value-prop statements, North Star metrics, naming, positioning |\n| `pm-toolkit` | Resume review, NDA drafting, privacy policy, grammar/flow checking |\n| `pm-ai-shipping` | AI Shipping Kit: document a vibe-coded app, map test coverage, audit security/performance against intended behavior, compile a shipping packet |\n\n## Key Design Rules\n\n- **Skills = nouns/concepts.** Frameworks and analytical knowledge Claude auto-loads when the topic matches (`lean-canvas`, `pre-mortem`, `market-sizing`).\n- **Commands = verbs.** User-triggered workflows that chain one or more skills (`/write-prd`, `/discover`, `/plan-launch`).\n- **No cross-plugin references.** Commands suggest follow-ups in natural language only (\"Want me to design growth loops?\"). Never hard-reference a command from another plugin — plugins install independently, so a hard reference can break.\n- **Intra-plugin \"Uses\" references are fine** — skills and commands in the same plugin always ship together.\n- Commands use a single `$ARGUMENTS` placeholder. Skills need no placeholders (they read context from the conversation).\n- **Frontmatter required:** Skills need `name` + `description`; commands need `description` + `argument-hint`.\n- A skill's `name` **must match its directory name**.\n- Skills can be force-loaded with `/plugin-name:skill-name` or `/skill-name`.\n- Keep frontmatter lean (always loaded); put detail in the SKILL.md body (loaded when triggered) — progressive disclosure.\n\n## What's Visible Where\n\n| Location | Visible in | Notes |\n|----------|-----------|-------|\n| `marketplace.json` → `description` | Cowork marketplace browser, Claude Code | One-liner for the whole marketplace |\n| `plugin.json` → `description` | Cowork plugin list, Claude Code | Per-plugin summary; concise and functional |\n| `SKILL.md` frontmatter → `description` | Cowork skill list, Claude auto-loading | Include trigger phrases so Claude loads the skill at the right time |\n| Command frontmatter → `description` + `argument-hint` | Cowork and Claude Code (typing `/`) | Short and actionable |\n| `README.md` (repo root) | GitHub only | Full docs; not loaded by Claude at runtime |\n\nDescriptions in `plugin.json` and the repo `README.md` should stay aligned (identical text).\n\n## Versioning & Releases\n\n- **`CHANGELOG.md` is the source of truth.** The newest `## vX.Y.Z — YYYY-MM-DD` heading is the released version. Pushing a commit to `main` that adds a new heading makes CI (`.github/workflows/tag-on-merge.yml`) verify the version sync and test suite, tag `vX.Y.Z`, and publish a GitHub Release with that section as notes.\n- **Keep every version in sync.** `marketplace.json`, all 9 `plugin.json` files, and the newest CHANGELOG heading always carry the same version (enforced by `tests/test_consistency.py`). There is no independent per-plugin versioning.\n- Every user-facing change gets a CHANGELOG bullet under `## Unreleased`; contributors are credited inline (`#PR, thanks @handle`). Full procedure: CONTRIBUTING.md § Releases.\n- Semver: breaking = major; new skills/commands or changed behavior = minor; fixes/docs = patch.\n\n## Article Links in Skills (Further Reading)\n\n- Mapped skills end with a `### Further Reading` section linking to relevant Product Compass articles.\n- **Tone must stay neutral** — no promotional language, no CTAs, no \"subscribe\"/\"check out\". Just the article title and URL.\n- Claude surfaces these links based on conversational relevance, not on every response.\n- Posts whose title contains \"Masterclass\" or \"Course\" are video courses — tag them `(video course)`.\n\n## Operational Procedures\n\n### After any skill/command change\n1. Run `python3 validate_plugins.py` and `python3 -m unittest discover -s tests` from the repo root.\n2. If skills/commands were added or removed, update the counts in `README.md` (headline + per-plugin summary + plugin README section headers — the tests check all three).\n3. If totals changed, update the count in the `marketplace.json` description.\n4. Add a `CHANGELOG.md` bullet under `## Unreleased` for any user-facing change.\n5. Bump versions across all manifests at release time (see Versioning & Releases).\n\n### After a description change\n- A `plugin.json` description changed → check whether `README.md` needs the same edit (they stay aligned).\n- A `SKILL.md` description changed → no other sync needed (it's the single source for that skill).\n\n## Validation\n\n`validate_plugins.py` checks: `plugin.json` required fields / name match / semver / author / keywords; skill frontmatter and name-matches-directory; command frontmatter (`description` + `argument-hint`); README presence; and intra-plugin command→skill references.\n\n`tests/` adds the consistency layer: README counts vs. disk, marketplace plugin list vs. directories, version sync across all manifests + CHANGELOG, CHANGELOG heading format, and `/plugin:command` references in plugin READMEs. Both run in CI on every PR and push to `main`, and gate releases.\n\n```\npython3 validate_plugins.py\npython3 -m unittest discover -s tests\n```\n\n## What to Suggest After Completing Work\n\nOffer relevant follow-ups:\n- After structural changes: \"Want me to run the validator?\"\n- After adding/removing skills or commands: \"Should I update the counts in README.md and marketplace.json?\"\n- After editing descriptions: \"Should I sync this to README.md / plugin.json?\"\n- After any repo change: \"Want me to bump the version?\"\n","AGENTS.md":"# AGENTS.md\n\nAll agent guidance for this repository lives in **[CLAUDE.md](CLAUDE.md)** — that is the single source of truth.\n\nPlease read [CLAUDE.md](CLAUDE.md) before making changes. This file exists only so non-Claude agents that look for `AGENTS.md` are pointed to the same instructions; do not duplicate guidance here.\n"}}