Back to Skills

Shipping Artifacts

The durable documentation set that makes an AI-built (vibe-coded) app reviewable before shipping. A small core every app needs — architecture, user/permission flows, permissions, variables/secrets, and a test-coverage map — plus conditional docs added only when they apply: email…

rustsecurityperformanceautomationairagagent
By phuryn
18k1.9kUpdated 1 week agoMIT

Skill Content

# Shipping Artifacts: The Docs That Make AI-Built Code Reviewable

## Purpose

AI agents write code fast, but they leave no durable record of *intent* — what the system is supposed to do, who is allowed to do what, where the secrets live, which rules are actually verified. Without that record, no human (and no auditing agent) can tell whether the code is safe to ship. This skill defines the small set of documents that restore reviewability.

These docs live in `/documentation/` and are written for two readers: a human reviewer and the next AI coding agent. They are the **intended-state** half of every later audit — a security or performance review is only as good as the intent it can compare the code against.

## How the set is organized

The set is **not** a fixed list — it is a small **core** plus **conditional** docs you add only when the capability exists.

- **Core docs** — every reviewable app has these surfaces, so always produce them.
- **Conditional docs** — include one only if the app actually has that capability. If it doesn't, write a single line in `architecture.md` ("No scheduled work — no `cron.md`.") rather than inventing an empty document. Reviewability comes from an honest map, and "we don't do X" is part of the map.
- Most docs are reverse-engineered from code by `/document-app`. The one exception is `tests.md`, which is *derived from the other docs* by `/derive-tests` — it is the verification map, not a description of a subsystem.

Be brutally honest about the current state without being paranoid. The job is an accurate map, not a clean bill of health. Each doc is short, table-and-bullet heavy, and skips generic theory.

## Core documents

Each entry: file · one-line purpose · what it must capture · how a reviewer uses it.

1. **`architecture.md`** — what the system is and how it hangs together.
   - Must capture: product overview + key assumptions; tech stack; how auth/sessions/claims flow end to end; the trust boundaries (e.g. service-role vs. client); a short **Known risks / assumptions** list (each entry backed by where it shows up in the code, not a generic checklist); a "Related Documents" index of every other doc produced.
   - Reviewer use: the root document — everything else is cross-referenced from here.

2. **`flows.md`** — the journeys where permissions and side effects are actually exercised.
   - Must capture: each load-bearing flow as actor + precondition + success outcome; the step-by-step sequence across UI → server → data → jobs → providers → agents; the **authz check at each protected step** (which claim/role/scope, on which resource, and the expected *deny* case); the **trust-boundary crossings** (browser→server, server→provider, job→app, agent→tool, webhook→app); the state changes and side effects each step causes (writes, emails queued, jobs triggered, outbound calls).
   - Reviewer use: the runtime view a static `permissions.md` matrix can't show — *where* and *in what order* authorization is enforced, and where it can be skipped.
   - **Anti-PRD rule:** a flow that doesn't touch permissions, data integrity, external side effects, money, privacy, or operational safety does not belong here. This is a security/operations map, not a feature spec.

3. **`permissions.md`** — who is allowed to do what.
   - Must capture: roles/claims; where scope is derived (token vs. DB); a resource × operation × role matrix; which tables have row-level security and which rely on code-enforced checks.
   - Reviewer use: the baseline an access-control audit compares the code against. `flows.md` shows it in motion; this is the static reference.

4. **`variables.md`** — configuration and secrets, mapped to risk.
   - Must capture: a table of Name · used-by · scope (server/client) · source · rotation · risk; explicit confirmation that no secret is bundled client-side; a pre-go-live checklist.
   - Reviewer use: the secrets/PII-leak surface and the rotation plan during incident response.

5. **`tests.md`** — the verification map: which documented rules are actually checked, which are only proposed, and which are checked by nothing.
   - Must capture, in three clearly separated sections so the map can't read falsely green:
     - **Existing coverage** — tests that are in the repo *today*, each tied to the rule it pins (so the map reflects reality, not a wish-list).
     - **Proposed tests** — recommended cases not yet written, marked by **test type** (automated unit/integration · guarded live · manual review).
     - **Gaps** — documented rules with no verification at all, ranked by what crossing them exposes.
   - Each row carries: use-case → rule → expected behavior (including the deny/negative case) → evidence source (doc + code) → status (existing / proposed / none). It also notes which checks are CI-required and gate merges to `main`.
   - Reviewer use: the operational form of "documented == implemented" — it shows whether each rule the other docs claim is actually pinned by a test today, only proposed, or unverified.
   - Produced by `/derive-tests` (not `/document-app`), because it is derived from the other docs and the existing test suite rather than read off a subsystem.

## Conditional documents (include only when the capability exists)

6. **`emails.md`** — every notification the system sends. *Include only if the app sends transactional or automated email.*
   - Must capture: the queue → processor → provider path; templates and the variables they accept; retry/backoff behavior; where to look when a send fails.
   - Reviewer use: spotting unvalidated template inputs and PII exposure boundaries.

7. **`cron.md`** — all scheduled work and how to operate it safely. *Include only if scheduled or background jobs exist.*
   - Must capture: an inventory table (job → schedule → function → secrets → limits → retry); how each job stays idempotent; how internal calls authenticate; where to see last runs.
   - Reviewer use: finding forgeable triggers and unbounded background jobs.

8. **`seo.md`** — how a single-page app handles SEO and social previews. *Include only if there are public/indexable or bot-facing routes.*
   - Must capture: the preview approach (static meta / prerender / edge HTML); a route → needs-SEO → public-data-only table; how dynamic metadata is sanitized; bot-vs-human routing.
   - Reviewer use: catching public-data-only violations and metadata injection on bot routes.

9. **`automation.md`** — embedded agents and other automation paths. *Include only if the app embeds AI agents, LLM workflows, tool-calling, webhooks, or external automation.*
   - Must capture, per automation/agent: trigger + owner + whether it runs automatically or only after approval; the inputs it may read and the **exact tools/APIs it may call** (the tool surface is itself a hard guardrail); where **steering** lives (the prompt) vs. the **non-prompt hard guardrails**; the **output contract** back to the app (schema, validation, failure handling); **app-owned side effects vs. agent-owned suggestions**; and the controls — approval gates, audit/timeline logging, rate limits, retries, kill switch.
   - Reviewer use: makes hidden automation paths visible and draws the line between what an agent *proposes* and what the app *enforces* — the highest-risk surface in modern AI-built apps.

## Notes

- Each produced doc adds a reference to itself in `architecture.md` under a "Related Documents" section, so the set stays discoverable.
- Skip any conditional document that doesn't apply, and say so in one line rather than inventing content.
- Keep examples and finished templates out of these docs — they describe *this* system, not the general method.
- The agent operating-context file (`CLAUDE.md` / `AGENTS.md`) is a *different* artifact — instructions derived from these docs, not system documentation. It is produced at the handoff step by `/ship-check`, not here.
- `tests.md` is produced by `/derive-tests`; the rest are produced by `/document-app`.
- Do not include an "updated date" line; the file's history is the source of truth.

How to use

  1. Copy the skill content above
  2. Create a .claude/skills directory in your project
  3. Save as .claude/skills/pm-skills-shipping-artifacts.md
  4. Use /pm-skills-shipping-artifacts in Claude Code to invoke this skill

GitHub stars License: MIT PRs Welcome Companion: pm-skills

PM Skills Marketplace: The AI Operating System for Better Product Decisions

68 PM skills and 42 chained workflows across 9 plugins. Claude Code, Cowork, and more. From discovery to strategy, execution, launch, growth, and shipping AI-built code.

PM Skills marketplace: skills, commands, and all 9 plugins at a glance

Designed for Claude Code and Cowork. Skills compatible with other AI assistants.

Start Here

New idea? → /discover
Need strategic clarity? → /strategy
Writing a PRD? → /write-prd
Planning a launch? → /plan-launch
Defining metrics? → /north-star

If this project helps you, ⭐ the repo.

Why PM Skills Marketplace?

Generic AI gives you text. PM Skills Marketplace gives you structure.

Each skill encodes a proven PM framework — discovery, assumption mapping, prioritization, strategy — and walks you through it step by step. You get the rigor of Teresa Torres, Marty Cagan, and Alberto Savoia built into your daily workflow, not sitting on a bookshelf.

The result: better product decisions, not just faster documents.

How It Works (Skills, Commands, Plugins)

Example prompts: a skill and two commands (/write-prd, /ship-check) in action

Skills are the building blocks of the marketplace. Each skill gives Claude domain knowledge, analytical frameworks, or a guided workflow for a specific PM task. Some skills also work as reusable foundations that multiple commands share.

Skills are loaded automatically when relevant to the conversation — no explicit invocation needed. If needed (e.g., prioritizing skills over general knowledge), you can force loading skills with /plugin-name:skill-name or /skill-name (Claude will add the prefix).

Commands are user-triggered workflows invoked with /command-name. They chain one or more skills into an end-to-end process. For example, /discover chains four skills together: brainstorm-ideas → identify-assumptions → prioritize-assumptions → brainstorm-experiments.

Plugins group related skills and commands into installable packages. Each plugin covers a PM domain — discovery, strategy, execution, and so on. Installing the marketplace gives you all 9 plugins at once.

Commands use skills. Some skills serve multiple commands. Some skills (like prioritization-frameworks or opportunity-solution-tree) are standalone references that Claude draws on whenever relevant — no command needed.

Commands are designed to flow into each other, matching the PM workflow. After any command completes, it suggests relevant next commands — just follow the prompts.

Installation

Claude Cowork (recommended for non-developers)

  1. Open Customize (bottom-left)
  2. Go to Browse pluginsPersonal+
  3. Select Add marketplace from GitHub
  4. Enter: phuryn/pm-skills

All 9 plugins install automatically. You get both commands (/discover, /strategy, etc.) and skills.

Installing PM Skills in Claude Cowork

Claude Code (CLI)

# Step 1: Add the marketplace
claude plugin marketplace add phuryn/pm-skills

# Step 2: Install individual plugins
claude plugin install pm-toolkit@pm-skills
claude plugin install pm-product-strategy@pm-skills
claude plugin install pm-product-discovery@pm-skills 
claude plugin install pm-market-research@pm-skills 
claude plugin install pm-data-analytics@pm-skills
claude plugin install pm-marketing-growth@pm-skills
claude plugin install pm-go-to-market@pm-skills
claude plugin install pm-execution@pm-skills
claude plugin install pm-ai-shipping@pm-skills

Codex CLI (OpenAI)

Codex reads the same plugin marketplace file as Claude Code, so you can install PM Skills natively — no conversion or file-copying needed:

# Step 1: Add the marketplace
codex plugin marketplace add phuryn/pm-skills

# Step 2: Install the plugins you want
codex plugin add pm-toolkit@pm-skills
codex plugin add pm-product-strategy@pm-skills
codex plugin add pm-product-discovery@pm-skills
codex plugin add pm-market-research@pm-skills
codex plugin add pm-data-analytics@pm-skills
codex plugin add pm-marketing-growth@pm-skills
codex plugin add pm-go-to-market@pm-skills
codex plugin add pm-execution@pm-skills
codex plugin add pm-ai-shipping@pm-skills

What you get: every skill (the PM frameworks), available to Codex and invocable by name. Install whole plugins rather than cherry-picking individual skills — a workflow usually relies on several skills that ship together.

What's different from Claude Code: the /slash commands (/discover, /write-prd, …) install but don't run as Codex slash commands — Codex plugins don't expose commands. To run a workflow, just describe the steps in plain language, for example:

Run product discovery on [your idea]: brainstorm options, map assumptions, prioritize the risky ones, then design experiments — pause between each step.

Optional — let Codex turn the workflows into skills. Because the command files ship inside each installed plugin, you can ask Codex to convert the ones you use most:

Read the command files in the pm-execution plugin and create equivalent Codex skills for the workflows I use most often.

This is a best-effort, model-driven conversion (some Claude-specific command syntax won't translate), but it's a quick way to get the guided workflows on Codex without leaving the CLI.

Other AI assistants (skills only)

The skills/*/SKILL.md files follow the universal skill format and work with any tool that reads it. Commands (/slash-commands) are Claude-specific.

ToolHow to useWhat works
Gemini CLICopy skill folders to .gemini/skills/Skills only
OpenCodeCopy skill folders to .opencode/skills/Skills only
CursorCopy skill folders to .cursor/skills/Skills only
KiroCopy skill folders to .kiro/skills/Skills only
# Example: copy all skills for OpenCode (project-level)
for plugin in pm-*/; do
  mkdir -p .opencode/skills/
  cp -r "$plugin/skills/"* .opencode/skills/ 2>/dev/null
done

# Example: copy all skills for Gemini CLI (global)
for plugin in pm-*/; do
  cp -r "$plugin/skills/"* ~/.gemini/skills/ 2>/dev/null
done

Available Plugins

<details> <summary><strong>1. pm-product-discovery</strong> — Ideation, experiments, assumption testing, OSTs, interviews (13 skills, 5 commands)</summary>

Skills (13):

  • brainstorm-ideas-existing — Multi-perspective ideation for existing products (PM, Designer, Engineer)
  • brainstorm-ideas-new — Ideation for new products in initial discovery
  • brainstorm-experiments-existing — Design experiments to test assumptions for existing products
  • brainstorm-experiments-new — Design lean startup pretotypes for new products (Alberto Savoia)
  • identify-assumptions-existing — Identify risky assumptions across Value, Usability, Viability, and Feasibility
  • identify-assumptions-new — Identify risky assumptions across 8 risk categories including Go-to-Market, Strategy, and Team
  • prioritize-assumptions — Prioritize assumptions using an Impact × Risk matrix with experiment suggestions
  • prioritize-features — Prioritize a feature backlog based on impact, effort, risk, and strategic alignment
  • analyze-feature-requests — Analyze and categorize customer feature requests by theme and strategic fit
  • opportunity-solution-tree — Build an Opportunity Solution Tree (Teresa Torres) — outcome → opportunities → solutions → experiments
  • interview-script — Create a structured customer interview script with JTBD probing questions
  • summarize-interview — Summarize an interview transcript into JTBD, satisfaction signals, and action items
  • metrics-dashboard — Design a product metrics dashboard with North Star, input metrics, and alert thresholds

Commands (5):

  • /discover — Full discovery cycle: ideation → assumption mapping → prioritization → experiment design
  • /brainstorm — Multi-perspective ideation (ideas|experiments × existing|new)
  • /triage-requests — Analyze and prioritize a batch of feature requests
  • /interview — Prepare an interview script or summarize a transcript (prep|summarize)
  • /setup-metrics — Design a product metrics dashboard

Examples:

Skills:

  • What are the riskiest assumptions for our AI writing assistant idea?
  • Help me build an Opportunity Solution Tree for improving user activation
  • Prioritize these 12 feature requests from our enterprise customers [attach CSV]

Commands:

  • /discover AI-powered meeting summarizer for remote teams
  • /brainstorm experiments existing — We need to reduce churn in our onboarding flow
  • /interview prep — We're interviewing enterprise buyers about their procurement workflow
</details> <details> <summary><strong>2. pm-product-strategy</strong> — Vision, business models, pricing, competitive landscape (12 skills, 5 commands)</summary>

Product strategy, vision, business models, pricing, and macro environment analysis. Covers the full strategic toolkit from vision crafting through competitive landscape scanning.

Skills (12):

  • product-strategy — Comprehensive 9-section Product Strategy Canvas (vision → defensibility)
  • startup-canvas — Startup Canvas combining Product Strategy (9 sections) + Business Model — an alternative to BMC and Lean Canvas for new products
  • product-vision — Craft an inspiring, achievable, and emotional product vision
  • value-proposition — 6-part JTBD value proposition (Who, Why, What before, How, What after, Alternatives)
  • lean-canvas — Lean Canvas business model for startups and new products
  • business-model — Business Model Canvas with all 9 building blocks
  • monetization-strategy — Brainstorm 3–5 monetization strategies with validation experiments
  • pricing-strategy — Pricing models, competitive analysis, willingness-to-pay, and price elasticity
  • swot-analysis — SWOT analysis with actionable recommendations
  • pestle-analysis — Macro environment: Political, Economic, Social, Technological, Legal, Environmental
  • porters-five-forces — Competitive forces analysis (rivalry, suppliers, buyers, substitutes, new entrants)
  • ansoff-matrix — Growth strategy mapping across markets and products

Commands (5):

  • /strategy — Create a complete 9-section Product Strategy Canvas
  • /business-model — Explore business models (lean|full|startup|value-prop|all)
  • /value-proposition — Design a value proposition using the 6-part JTBD template
  • /market-scan — Macro environment analysis combining SWOT + PESTLE + Porter's + Ansoff
  • /pricing — Design a pricing strategy with competitive analysis and experiments

Examples:

Skills:

  • Compare Lean Canvas vs Business Model Canvas vs Startup Canvas for my marketplace startup
  • Design a value proposition for our AI writing assistant targeting non-native English speakers
  • Run a Porter's Five Forces analysis for the project management SaaS market

Commands:

  • /strategy B2B project management tool for agencies
  • /business-model startup — AI writing tool for non-native English speakers
  • /value-proposition SaaS onboarding tool for enterprise customers
</details> <details> <summary><strong>3. pm-execution</strong> — PRDs, OKRs, roadmaps, sprints, retros, release notes, stakeholder management (16 skills, 11 commands)</summary>

Day-to-day product management: PRDs, OKRs,

View source on GitHub