Skip to content
pm-skills

Authoring Sub-Agents

Table of Contents

Prerequisites

Before authoring a new sub-agent:

  • Read docs/concepts/sub-agents.md for the component-class mental model
  • Read docs/contributing/sub-agent-design-patterns.md for the 4 invocation patterns + composition patterns
  • Confirm your proposed sub-agent fits the “isolated context + action-taking” use case; if the work is content-production, a skill is the right fit
  • Have a clear behavioral spec ready (audience, mission, refusal protocols, severity grammar - same shape as the 4 spec docs in docs/internal/release-plans/v2.16.0/spec_pm-*.md)

File Structure

pm-skills/
+-- .claude-plugin/
|   +-- plugin.json                       # Plugin manifest
+-- agents/
|   +-- _pairing.yaml                      # Sub-agent + companion command pairings
|   +-- _chain-permitted.yaml              # Allowlist for agents that may use Agent tool
|   +-- pm-your-new-agent.md               # NEW: your sub-agent definition
+-- commands/
|   +-- your-verb.md                       # NEW: companion slash command (verb-shaped)
+-- skills/
|   +-- utility-pm-your-new-agent/         # NEW: dispatch skill (conditional on cross-client support)
|       +-- SKILL.md
|       +-- references/
|           +-- TEMPLATE.md
|           +-- EXAMPLE.md
+-- library/
|   +-- sub-agent-samples/
|       +-- pm-your-new-agent/             # NEW: 3 thread-aligned samples
|           +-- sample_pm-your-new-agent_brainshelf_*.md
|           +-- sample_pm-your-new-agent_storevine_*.md
|           +-- sample_pm-your-new-agent_workbench_*.md
+-- docs/
|   +-- reference/
|   |   +-- runtime-components.md          # ADD: new row in sub-agents catalog
|   +-- guides/                            # (optional) per-agent user guide
|   +-- contributing/                      # (optional) per-agent contributor guide
+-- AGENTS.md                              # ADD: utility-pm-your-new-agent dispatch skill entry

Sub-agent definitions live in the fixed agents/ directory at the plugin root, which Claude Code’s plugin runtime auto-discovers. There is no plugin.json field for a custom path. The directory was named subagents/ through v2.16.x to avoid a case-insensitivity collision with the then-uppercase AGENTS/ coordination directory; v2.17.0 (W2) renamed that coordination directory to _agent-context/, freeing agents/ for native discovery.

Frontmatter Convention

Required fields per Claude Code plugin spec:

---
name: pm-your-new-agent
description: |
  Multi-line description that Claude Code's intent classifier matches on.
  Include "use proactively" if the agent should auto-fire (only for user-facing
  reviewers like pm-critic; explicit-only for utility agents).
  Be specific about what artifacts / contexts trigger invocation.
tools: Read, Grep, Glob
model: sonnet
memory: none
---

Field discipline:

  • name: must match the filename (agents/pm-your-new-agent.md -> name: pm-your-new-agent)
  • description: is the intent-classifier match surface; write for discoverability
  • tools: is a comma-separated scalar (D20). Common: Read, Grep, Glob, Bash, Edit, Agent (chain composition only)
  • model: typically sonnet; use opus for high-reasoning critical paths if justified
  • memory: default none; escalate to project only with 3+ runs of evidence

Tools restriction: if you include Agent in tools: (for chain composition), you MUST add your sub-agent name to agents/_chain-permitted.yaml per master plan D21. Otherwise validate-agents-md fails CI with HARD FAIL.

Referential Discipline

Do not embed canonical standards content in the system prompt. Per master plan D12, sub-agents read canonical contract docs at INVOCATION TIME, not at AUTHORING TIME.

Wrong (embeds standards content; drift risk):

You are pm-critic. When reviewing OKR sets, apply these refusal protocols:
- Fabricated baselines must refuse
- Comp coupling must refuse
- Feature-delivery KRs must refuse
... [200 lines of embedded OKR refusal rules]

Right (referential):

You are pm-critic. When reviewing OKR sets, read
`skills/foundation-okr-writer/SKILL.md` at invocation time for the
canonical refusal protocols. Apply those protocols.

The referential pattern means:

  • Standards docs are the single source of truth
  • Sub-agent goes stale only if it can no longer find the doc; never goes stale because it has out-of-sync embedded content
  • New standards added to the canonical doc apply automatically without re-authoring the sub-agent

Phase 8 integration check verifies no embedded duplication.

Severity Grammar

All sub-agents producing findings use P0 / P1 / P2 / P3 uniformly (master plan D15):

SeverityMeaningAction expected
P0Blocks ship. Will cause real-world harm if shipped as-is.Must fix.
P1Fix before next major review. Significant gap.Fix before workflow stage advances.
P2Consider. Quality opportunity.Author judgment.
P3Nit. Cosmetic or style.Skip if time-constrained.

Every finding MUST include a concrete fix suggestion. “This is unclear” is NOT a finding; “Rewrite as X to address Y” IS a finding.

Companion Command Pairing

Per master plan D6, every sub-agent ships with a companion slash command in commands/. Convention:

  • Sub-agent name: pm-{role} (e.g., pm-critic)
  • Command name: verb-shaped (e.g., /pm-critic, /pm-audit-repo, /pm-draft-changelog, /pm-release)
  • Declare the pairing in agents/_pairing.yaml

Command body (commands/your-verb.md) follows the standard pm-skills command convention:

---
description: One-line description of what the command does
argument-hint: "[optional argument shape]"
---


Use the `pm-{role}` sub-agent to {do the thing}.


If `$ARGUMENTS` contains a {specific input shape}, use that. Otherwise {fallback behavior}.


[Brief explanation of what the sub-agent does and where the canonical docs live]


Context from user: $ARGUMENTS

The command body MUST reference a skills/[a-z0-9-]+/SKILL.md path for scripts/validate-commands.sh to pass. Reference the dispatch skill path (skills/utility-pm-{role}/SKILL.md).

Chain Composition (Advanced)

If your sub-agent needs to invoke another sub-agent (Pattern 3 from docs/contributing/sub-agent-design-patterns.md):

  1. Include Agent in tools: frontmatter
  2. Add your sub-agent name to agents/_chain-permitted.yaml
  3. Verify chain depth stays at 2 max (per D14): if your child can also chain, you would have a 3-level chain; remove Agent from the child’s tools

The only chain-permitted sub-agent in v2.16.0 is pm-release-conductor. Adding a new chain-permitted agent is security-relevant and requires maintainer review.

Dispatch Skill (for Cross-Client Access)

Per master plan D30, sub-agents are Claude Code plugin features. To deliver the same intent to non-Claude clients, ship a dispatch skill at skills/utility-pm-{role}/.

Dispatch skill SKILL.md structure (~50-100 lines):

---
name: utility-pm-{role}
description: {one-line description; reference dispatch mechanism}
classification: utility
version: "1.0.0"
updated: 2026-MM-DD
license: Apache-2.0
metadata:
  category: {category}
  frameworks: [triple-diamond]
  author: product-on-purpose
---


# {Role} (Dispatch Skill)


[Conditional instructions for Claude Code vs other clients]


## Instructions


### If you are running in Claude Code with the pm-skills plugin installed


Invoke `@agent-pm-{role}` on the target with `$ARGUMENTS`. Return findings.


### If you are running in any other AI client


1. Read the canonical sub-agent definition at `agents/pm-{role}.md`
2. Execute the system prompt body as your operating instructions
3. {agent-specific steps}
4. Return the layered output per master plan D26 (full findings + Status Summary + Status YAML)

Then references/TEMPLATE.md documents the output format and references/EXAMPLE.md shows a worked example on a specific non-Claude client.

Library Samples (3 per Sub-Agent)

Per master plan SI5, sub-agents ship Tier 0 (one per sub-agent) for the v2.16 release, expanding to 3 thread-aligned samples per sub-agent in Phase 6 of subagents-integration-plan.

The 3 thread conventions:

  • Brainshelf: consumer PKM app (e.g., reading-list, save-and-return)
  • Storevine: B2B campaign analytics (e.g., dashboards, OKRs, optimization)
  • Workbench: internal platform tooling (e.g., DX, infra, platform-team meetings)

Sample shape: scenario + output + notes. Frontmatter includes artifact:, thread:, agent_version:, repo_version:, status: sample.

Behavioral Spec Doc

Before authoring the sub-agent file itself, write a spec doc at docs/internal/release-plans/v{X.Y.Z}/spec_pm-{role}.md covering:

  • Identity (name, classification, tier, audience, version, license)
  • Mission (one paragraph; what the sub-agent does at its core)
  • Behavior Contract (what it does; what it does NOT do; refusal protocols)
  • Severity grammar (default P0/P1/P2/P3; deviations require justification)
  • Inputs and Outputs (signature; output format)
  • Invocation Patterns (which of the 4 patterns this sub-agent uses)
  • Tool Surface (rationale for each tool)
  • Memory and Lifetime
  • Frontmatter (canonical for the sub-agent file)
  • System Prompt Structure (referential outline)
  • Composition with Other Components
  • Cross-Client Compatibility (dispatch skill plan)
  • Library Sample Coverage (3 thread-aligned)
  • Acceptance Criteria (checklist for “ready to ship”)
  • Risks Specific to This Sub-Agent
  • Out of Scope for This Release
  • Cross-References

The 4 v2.16 spec docs at docs/internal/release-plans/v2.16.0/spec_pm-{critic,skill-auditor,changelog-curator,release-conductor}.md are canonical examples.

Validation Checklist

Before merging a new sub-agent:

  • agents/pm-{role}.md exists with valid frontmatter
  • commands/{verb}.md exists and references the dispatch skill path
  • agents/_pairing.yaml lists the new pair
  • If Agent is in tools, agents/_chain-permitted.yaml lists the new agent
  • skills/utility-pm-{role}/ exists with SKILL.md + references/TEMPLATE.md + references/EXAMPLE.md (or rationale documented for skipping if intentional)
  • docs/reference/runtime-components.md has the new row populated
  • AGENTS.md has the new dispatch skill entry in Utility Skills section
  • library/sub-agent-samples/pm-{role}/ has at least 1 sample for ship-day (3 by end of cycle)
  • Spec doc exists at docs/internal/release-plans/v{version}/spec_pm-{role}.md
  • System prompt is referential (no embedded standards content)
  • Severity grammar uses P0/P1/P2/P3 uniformly
  • validate-agents-md.sh passes
  • validate-commands.sh passes for the new command
  • lint-skills-frontmatter.sh passes for the dispatch skill
  • Em-dash sweep clean across all new files