Skip to content
pm-skills

Runtime Components

Table of Contents

What Runtime Components Are

pm-skills ships two layers of capability:

Content library (the bulk of the repo): 63 skills, 73 slash commands, 12 workflows, 27 enforcing CI validators. Skills are content - reference material an AI reads at invocation time. They do not execute logic on their own.

Runtime components (this catalog): Plugin features that take action. Sub-agents are dispatched by Claude Code’s intent classifier and run in their own context window. Hooks fire on lifecycle events (PreToolUse, PostToolUse, Stop). Output styles transform how Claude formats responses.

The distinction matters because skills are portable across clients (any client that supports the agentskills.io specification can read SKILL.md files), but runtime components are Claude Code plugin-specific. pm-skills delivers sub-agent intent to non-Claude clients via dispatch skills (see Cross-Client Compatibility) so users on Codex CLI, Cursor, Windsurf, Copilot, or Gemini CLI lose no functional access.

LayerWhat it isHow AI uses itCross-client portable?
Skills (63)Reference content with frontmatter, templates, examplesAI reads SKILL.md at invocation timeYes (per agentskills.io spec)
Commands (73)Slash command wrappers that invoke skills with argumentsUser types /skill-name, AI executes the linked skillClaude Code native; portable conceptually
Workflows (12)Multi-skill chains for full lifecycle momentsAI walks ordered skill invocationsNative; portable conceptually
Sub-agents (4 in v2.16)Plugin components matched via description: and run in isolated contextClaude Code’s intent classifier delegates; OR user invokes companion slash commandClaude Code only; dispatch skills provide cross-client parity
Hooks (0; v2.17+ scope)Lifecycle event handlers (PreToolUse, PostToolUse, Stop, etc.)Claude Code fires automatically on configured eventsClaude Code only
Output styles (0; v2.18+ scope)Response formatting transformsClaude applies when style is activeClaude Code only

Sub-Agents Catalog

v2.16.0 introduces sub-agents as the first runtime-component class. 4 sub-agents ship in this release. Each definition lives at agents/{name}.md, the fixed path Claude Code’s plugin runtime auto-discovers (the directory was named subagents/ through v2.16.x and renamed to agents/ in v2.17.0 W2; see project structure).

Sub-agentAudienceTriggerLifetimeTool SurfaceCompositionDispatch Skill
pm-criticUser (PM authoring artifacts)Proactive after PM-artifact-producing skills (Claude Code) + explicit /pm-criticSingle turnRead, Grep, Glob (no write; no Bash)Skill-revise-recheck loop with deliver-prd, foundation-okr-writer, foundation-meeting-recap, foundation-persona, foundation-lean-canvas, discover-interview-synthesis, etc.skills/utility-pm-critic/
pm-skill-auditorUser + Maintainer (audience straddles)Explicit only: /pm-audit-repo or @agent-pm-skill-auditor; chained from pm-release-conductor at gate G0Multi-turn (may ask follow-up questions)Bash, Read, Grep, Glob (no Edit; no Agent; detection-only)Composes the enforcing validator suite via scripts/pre-tag-validate.{sh,ps1}; runs cross-cutting checks; re-derives aggregate countersskills/utility-pm-skill-auditor/
pm-changelog-curatorMaintainerExplicit only: /pm-draft-changelog or @agent-pm-changelog-curator; chained from pm-release-conductor at gate G2Single turn (standalone or chained)Bash, Read, Grep (no Edit; no Agent)Composes with git log + CLAUDE.md hygiene rules; chained from conductor at G2skills/utility-pm-changelog-curator/
pm-release-conductorMaintainerExplicit only: /pm-release v{X.Y.Z} (no @-mention; release too consequential for ambient spawn)Full release flow (often 30+ minutes)Bash, Read, Edit, Grep, Glob, Agent (chain-permitted per _chain-permitted.yaml)Chains to pm-skill-auditor at G0 + G2.5 and to pm-changelog-curator at G2; reads docs/contributing/release-runbook.md for gate definitionsskills/utility-pm-release-conductor/

For per-sub-agent cross-client status (Claude Code / Codex CLI / Cursor / Windsurf / Copilot CLI / Gemini CLI), see the canonical Sub-Agent Compatibility Matrix. Rows fill in as each sub-agent ships in its respective phase of subagents-integration-plan.md. Behavioral contracts live in the corresponding spec_pm-{name}.md files alongside the integration plan.

Sub-agent invariants

These invariants hold for every sub-agent in this catalog (enforced by scripts/validate-agents-md.{sh,ps1} extended per master plan D19):

  • Definition file at agents/{name}.md with YAML frontmatter declaring name, description, tools, model, memory
  • Companion slash command at commands/{verb}.md per master plan D6, paired in agents/_pairing.yaml
  • tools: frontmatter is a comma-separated scalar (per D20), e.g. tools: Read, Grep, Glob
  • Agent in tools: requires entry in agents/_chain-permitted.yaml per D21 (HARD FAIL otherwise)
  • Chain depth capped at 2 levels (D14)
  • Severity grammar P0 / P1 / P2 / P3 across all findings output (D15)
  • System prompt is referential, not duplicative (D12)
  • Default memory: none unless escalation is justified (D13)

Hooks Catalog

No hooks ship in v2.16.0. The roadmap’s PostToolUse frontmatter hook (R-24) is deferred to v2.17 once sub-agents are battle-tested; the hook-triggered sub-agent invocation pattern (R-65) depends on the v2.16 sub-agent slate landing first.

HookEventStatus
(none in v2.16.0)(none)v2.17+ scope

Output Styles Catalog

No output styles ship in v2.16.0. The roadmap’s PM Voice output style (R-45) is deferred to v2.18+.

StylePurposeStatus
(none in v2.16.0)(none)v2.18+ scope

How to Discover and Invoke

Native Claude Code path

Sub-agents are discovered automatically when the pm-skills plugin is installed. Two invocation paths exist:

Proactive (Claude Code matches description: and dispatches):

User: "Here's the PRD draft for review."
Claude Code: [intent classifier matches pm-critic's `use proactively` description]
             [dispatches to pm-critic in fresh context window]
             [pm-critic reads PRD, produces P0-P3 findings, returns to main context]
Claude: "I've reviewed your PRD. Three P1 findings to address..."

Only pm-critic ships with a proactive trigger in v2.16.0 per master plan D7. The 3 utility sub-agents (pm-skill-auditor, pm-changelog-curator, pm-release-conductor) are explicit-only.

Explicit (user invokes the companion slash command):

User: /pm-critic docs/specs/my-prd.md
Claude Code: [invokes pm-critic with the artifact path as $ARGUMENTS]

Companion slash commands per agents/_pairing.yaml:

  • /pm-critic [artifact path] invokes pm-critic
  • /pm-audit-repo invokes pm-skill-auditor
  • /pm-draft-changelog [since-tag] invokes pm-changelog-curator
  • /pm-release [version] invokes pm-release-conductor

Dispatch skill path (non-Claude clients)

On non-Claude clients (Codex CLI, Cursor, Windsurf, Copilot, Gemini CLI), sub-agents are not natively available. Users invoke the dispatch skill at skills/utility-pm-{role}/ which provides the same intent. The dispatch skill SKILL.md detects runtime and either:

  1. (Claude Code path) invokes the native sub-agent via @agent-pm-{role} syntax, OR
  2. (Non-Claude path) reads agents/pm-{role}.md and executes its system prompt inline

See Cross-Client Compatibility for details. Dispatch skill availability is conditional on Phase 2 spike outcomes; see the integration plan.

Cross-Client Compatibility

Per master plan D11 (amended) + D30:

Single-tool user assumption. pm-skills does NOT assume users run multiple AI tools simultaneously. Users typically pick ONE primary AI tool (Claude Code, Codex CLI, Cursor, Windsurf, Copilot, or Gemini CLI) for a given workflow. pm-skills delivers full value to all clients, but the SHAPE of the access differs:

ClientSkills accessSub-agent access
Claude CodeNative plugin install; auto-discoveryNative plugin sub-agent at agents/{name}.md
Codex CLISync to ~/.codex/skills/ per agentskills.ioDispatch skill at skills/utility-pm-{role}/ reads agents/{name}.md inline
CursorSync to .cursor/skills/Same dispatch pattern
WindsurfSync to .windsurf/skills/Same dispatch pattern
CopilotSync to .copilot/skills/Same dispatch pattern
Gemini CLISync to .gemini/skills/Same dispatch pattern

Dispatch skill mechanism. Each dispatch skill is a thin pm-skills utility skill (~50 lines of SKILL.md) that contains conditional instructions:

If you are running in Claude Code with the pm-skills plugin: invoke @agent-pm-critic (or equivalent) on the target. If you are running in any other client: read the canonical agent definition at agents/pm-{name}.md and execute the system prompt body as your operating instructions for this turn.

The dispatch skill is portable per agentskills.io. The sub-agent definition file (agents/{name}.md) is portable as plain markdown - any AI that can read a file can execute its prompt body inline. There is no drift risk: the canonical system prompt lives in ONE place (the sub-agent definition), and the dispatch skill references it.

codex-rescue is NOT a baseline. Prior framing (pre-amendment) assumed users had Claude Code AND Codex CLI AND the codex-rescue plugin. None of these are universal. codex-rescue is an optional shortcut for the minority of users running both Claude Code and Codex CLI; it is not part of the dispatch path.

Functional gaps on non-Claude clients (acceptable per single-tool user assumption):

  • Proactive triggering (pm-critic’s auto-fire after PM-artifact-producing skills) is a Claude Code frontmatter feature. On non-Claude clients, sub-agent invocation is explicit-only.
  • User-level overrides via .claude/agents/ (Claude Code’s per-user agent dir) have no portable equivalent. Non-Claude users edit the dispatch skill SKILL.md locally instead.
  • Plugin-level settings via .claude/pm-skills.local.md (deferred to v2.17+) are Claude-Code-specific.

These gaps are documented but not blocking; they reflect the platform differences, not pm-skills design choices.

Composition Patterns

pm-skills sub-agents compose with each other and with the skills library in specific patterns. The strategy doc at docs/internal/_working/subagents/subagent-strategy_2026-05-07.md catalogs all patterns; this section summarizes the v2.16.0 active ones.

Pattern 1: Skill -> sub-agent (proactive review loop)

A PM-artifact-producing skill (deliver-prd, foundation-okr-writer, foundation-meeting-recap, foundation-persona, foundation-lean-canvas, discover-interview-synthesis) emits its artifact. pm-critic’s proactive trigger fires, runs adversarial review, returns P0-P3 findings. The user iterates on the artifact based on findings.

Pattern 2: Slash command -> sub-agent (explicit invocation)

User runs /pm-critic, /pm-audit-repo, /pm-draft-changelog, or /pm-release. The command invokes the paired sub-agent. Single-turn lifetime for critic and curator; multi-turn for auditor and conductor.

Pattern 3: Sub-agent -> sub-agent (chain composition, 2 levels max)

pm-release-conductor chains to children at specific gates:

  • G0 (pre-tag readiness): chains to pm-skill-auditor; receives audit findings via layered Status envelope per D26
  • G2 (CHANGELOG prep): chains to pm-changelog-curator; receives draft via layered Status envelope per D26
  • G2.5 (commit + re-verify): re-runs G0 chain after committing release-prep edits per D22

Neither child (auditor, curator) chains further. Chain depth = 2 is enforced via agents/_chain-permitted.yaml allowlist + validate-agents-md (D21 HARD FAIL).

Pattern 4: Dispatch skill -> sub-agent or inline execution (cross-client)

Dispatch skill detects runtime and either invokes native sub-agent (Claude Code path) or reads + executes the agent definition inline (non-Claude path). The “reference + execute inline” pattern enables non-Claude clients to consume sub-agent intent without losing functional access.

For pm-release-conductor specifically (most complex sub-agent), the dispatch skill uses an expanded “reference + execute inline” pattern that inlines auditor + curator behaviors at G0 + G2 on non-Claude clients (instead of chaining; chain composition is Claude Code only). This pattern is validated by Phase 2 GATE C sub-spike before shipping the conductor dispatch skill.

Cross-References