deanpeters__product-manager-skills/26APR26.md

TASK: Product Manager Skills Release Packaging Automation

You are working in the Product-Manager-Skills repository.

Goal

Make this repository easy for nontechnical product managers, Claude Desktop/Web users, Claude Code users, and Codex users to consume.

The desired outcome is:

1. A maintainer can run one command to build all release artifacts.
2. GitHub Actions automatically builds downloadable packages on version tags.
3. Claude Desktop/Web users can download ZIP skill packs.
4. Claude Code users can keep using the plugin marketplace pattern.
5. Codex users can use repo-native .agents/skills plus AGENTS.md.
6. The README clearly tells each user which path to use.

Do not remove existing Claude Code support. Do not break the existing skills/ directory. Treat skills/ as the canonical source of truth.

---

Current/Expected Repo Shape

Assume the repo has or should have:

skills/
  <skill-name>/
    SKILL.md

.claude-plugin/
  marketplace.json

scripts/
  zip-a-skill.sh

You may inspect the repo and adapt to the actual structure.

---

Required Deliverables

Create or update the following:

scripts/
  validate-skills.sh
  build-claude-desktop-packs.sh
  build-codex-skills.sh
  build-release.sh

.github/
  workflows/
    build-release.yml

AGENTS.md

docs/
  INSTALL-CLAUDE-DESKTOP.md
  INSTALL-CLAUDE-CODE.md
  INSTALL-CODEX.md
  RELEASE-PACKAGING.md

README.md

If some files already exist, update them conservatively.

---

Packaging Strategy

Use this model:

skills/                      # canonical source
dist/
  claude-desktop/
    01-core-pm-starter-pack.zip
    02-discovery-pack.zip
    03-strategy-pack.zip
    04-delivery-pack.zip
    05-ai-pm-pack.zip
    99-all-skills-pack.zip

  codex/
    .agents/
      skills/
        <skill-name>/
          SKILL.md
    AGENTS.md
    codex-product-manager-skills.zip

  release/
    Product-Manager-Skills-<version>.zip

The exact version may come from the Git tag, package metadata, or fallback to dev.

---

Script 1: scripts/validate-skills.sh

Create a validation script that:

1. Finds every immediate child directory under skills/.

2. Verifies each skill directory contains SKILL.md.

3. Verifies each SKILL.md contains YAML front matter.

4. Verifies front matter includes:

   • name:
   • description:

5. Prints a readable summary:

   • number of skills found
   • number valid
   • any missing fields

6. Exits nonzero if validation fails.

Keep it POSIX/Bash friendly. Do not require Python unless already used in the repo.

---

Script 2: scripts/build-claude-desktop-packs.sh

Create a script that builds ZIP packs suitable for Claude Desktop/Web upload.

Requirements:

1. Clean and recreate dist/claude-desktop/.
2. Build individual or preset ZIPs using the existing zip-a-skill.sh where possible.
3. If zip-a-skill.sh already supports presets, reuse it.
4. If presets do not exist, add a simple preset mechanism.

Required packs:

01-core-pm-starter-pack.zip
02-discovery-pack.zip
03-strategy-pack.zip
04-delivery-pack.zip
05-ai-pm-pack.zip
99-all-skills-pack.zip

Suggested preset mappings. Adjust only if the repo has clearly better names:

core-pm:
  user-story
  jobs-to-be-done
  prioritization-advisor
  product-strategy-session
  roadmap-planning
  discovery-process

discovery:
  discovery-process
  jobs-to-be-done
  customer-interview
  persona
  problem-statement
  opportunity-solution-tree

strategy:
  product-strategy-session
  positioning
  value-proposition
  business-model
  market-analysis
  competitive-analysis

delivery:
  user-story
  acceptance-criteria
  release-planning
  roadmap-planning
  backlog-refinement

ai-pm:
  ai-product-management
  ai-use-case
  agent-journey-map
  prompt-design
  ai-risk-assessment

If a listed skill does not exist, warn and continue. Do not fail the build unless a pack ends up empty.

Each generated pack should contain skill folders with their SKILL.md files preserved.

---

Script 3: scripts/build-codex-skills.sh

Create a script that builds Codex-friendly skills from canonical skills/.

Requirements:

1. Clean and recreate:

dist/codex/.agents/skills/

2. Copy each canonical skill directory from:

skills/<skill-name>/

to:

dist/codex/.agents/skills/<skill-name>/

3. Copy root AGENTS.md into:

dist/codex/AGENTS.md

4. Create:

dist/codex/codex-product-manager-skills.zip

The ZIP should contain:

.agents/
  skills/
    <skill-name>/
      SKILL.md
AGENTS.md

Do not include .git, dist, or unnecessary repo files.

---

Script 4: scripts/build-release.sh

Create a top-level release builder that:

1. Runs validate-skills.sh.
2. Runs build-claude-desktop-packs.sh.
3. Runs build-codex-skills.sh.
4. Copies useful docs into dist/release/.
5. Creates one downloadable master artifact:

dist/Product-Manager-Skills-<version>-release.zip

The release ZIP should include:

claude-desktop/
codex/
docs/
README.md

Use the Git tag as version when available:

git describe --tags --exact-match 2>/dev/null

Fallback to:

dev

Print final artifact paths.

---

GitHub Action: .github/workflows/build-release.yml

Create a GitHub Action that:

1. Runs on:

   • pull requests
   • pushes to main
   • version tags matching v*

2. On PR/main:

   • run validation
   • run build
   • upload artifacts for inspection

3. On version tags:

   • run validation

   • run build

   • create or update a GitHub Release

   • attach:

     • dist/Product-Manager-Skills-*-release.zip
     • all ZIPs under dist/claude-desktop/
     • dist/codex/codex-product-manager-skills.zip

Use stable GitHub Actions:

• actions/checkout@v4
• actions/upload-artifact@v4
• softprops/action-gh-release@v2

Use GITHUB_TOKEN.

---

Root AGENTS.md

Create a repo-level AGENTS.md for Codex.

It should say:

# Product Manager Skills

This repository contains reusable product management skills for AI agents.

## How to Work in This Repo

- Treat `skills/` as the canonical source of truth.
- Do not edit generated files under `dist/` directly.
- Preserve compatibility with Claude Desktop/Web, Claude Code, and Codex.
- Prefer small, maintainable Bash scripts over complex build systems.
- Validate all skills before packaging.
- Do not rename skills unless necessary.
- Do not delete existing Claude Code marketplace files.

## Skill Guidance

When users ask for product management help, inspect available skills before improvising.

Relevant topics include:
- discovery
- Jobs to be Done
- personas
- product strategy
- prioritization
- roadmaps
- PRDs
- user stories
- acceptance criteria
- AI product management
- agent workflows
- stakeholder alignment

Prefer the most specific skill.

These are product management coaching and artifact-generation workflows, not software engineering workflows.

## Build Commands

Run:

```bash
./scripts/validate-skills.sh
./scripts/build-release.sh

---

## Documentation

Create concise docs.

### `docs/INSTALL-CLAUDE-DESKTOP.md`

Explain:

1. Go to GitHub Releases.
2. Download `01-core-pm-starter-pack.zip` or another pack.
3. Open Claude.
4. Go to Settings → Capabilities → Skills.
5. Upload the ZIP.
6. Start a new chat and ask Claude to use the Product Manager Skills.

Include a “Which pack should I choose?” table.

### `docs/INSTALL-CLAUDE-CODE.md`

Explain:

1. Use the existing plugin marketplace.
2. Include commands like:

```text
/plugin marketplace add deanpeters/Product-Manager-Skills
/plugin install jobs-to-be-done@pm-skills
/reload-plugins

3. Explain that Claude Code users should usually use the marketplace, not the Claude Desktop ZIPs.

docs/INSTALL-CODEX.md

Explain:

1. Download codex-product-manager-skills.zip.
2. Unzip it into a project or repo root.
3. Confirm the project has:

.agents/skills/
AGENTS.md

4. Open Codex in that repo.
5. Ask Codex to use a named skill.

Example:

Use the jobs-to-be-done skill to analyze this customer problem.

Also explain that advanced users can clone the whole repo and run Codex from the repo root.

docs/RELEASE-PACKAGING.md

Explain maintainer flow:

./scripts/build-release.sh
git tag v0.76.0
git push origin v0.76.0

Explain generated artifacts and where they go.

---

README Updates

Update the top of README.md with a clear “Start Here” section.

Use this structure:

## Start Here

Choose your setup:

| I use... | Download/use this | Best for |
|---|---|---|
| Claude Desktop / Claude Web | `01-core-pm-starter-pack.zip` | Nontechnical PMs |
| Claude Code | Plugin marketplace | Terminal users |
| Codex | `codex-product-manager-skills.zip` or repo clone | Codex CLI/app users |
| I am not sure | `01-core-pm-starter-pack.zip` | Most people |

### Fastest Path

Download the starter pack from Releases:

`01-core-pm-starter-pack.zip`

Upload it to Claude Skills.

Ask:

“Use the Product Manager Skills to help me frame this product problem.”

Keep existing README content, but move deeper technical details lower.

---

Quality Bar

Before finishing:

1. Run:

./scripts/validate-skills.sh
./scripts/build-release.sh

2. Confirm ZIP files exist.
3. Confirm no generated ZIPs are accidentally committed unless the repo already commits dist/.
4. Confirm docs link to one another.
5. Confirm scripts are executable.
6. Confirm GitHub Action YAML is valid.
7. Summarize changed files and how to test.

---

Important Constraints

• Do not require Node, Python, Ruby, or other runtime unless already used.
• Prefer Bash plus common Unix tools.
• Use zip if available.
• If zip is missing, print a helpful error.
• Do not remove existing files unless clearly obsolete.
• Do not break existing Claude Code marketplace support.
• Keep nontechnical users in mind.
• The release experience should feel like:

Download one pack. Upload one file. Start asking better product questions.

## How I’d run it in Codex

From the repo root:

```bash
codex

Then paste the task above.

After Codex makes changes, ask it:

Review your own changes against the task. Identify anything incomplete, risky, or likely to fail in GitHub Actions.

Then:

Run the build scripts and fix any errors until the release artifacts generate correctly.

Tiny packaging gospel:

/skills is the source. /dist is the shelf. GitHub Releases is the storefront. The README is the confused customer rescue desk.