Skip to content
pm-skills

v2.17.0 Release Notes - Native Sub-Agent Registration + Frontmatter Spec Alignment

Released: 2026-05-20 Type: Minor (structural; same 59-skill catalog as v2.16.x) Day-to-day usage: identical for all skills, commands, and workflows. On Claude Code the 4 sub-agents now dispatch via native @-mention; on other clients the dispatch skills work exactly as before.

TL;DR

v2.17.0 closes the architectural gap that v2.16.x carried as a Known Limitation: the 4 sub-agents (pm-critic, pm-skill-auditor, pm-changelog-curator, pm-release-conductor) now register natively on Claude Code. Their definitions live in the canonical agents/ directory, so they auto-discover and dispatch via @-mention (@pm-critic, etc.).

Two coordinated directory renames make this work on case-insensitive filesystems (Windows NTFS, macOS APFS):

  • subagents/ to agents/ (the sub-agent definitions; now auto-discovered)
  • AGENTS/ to _agent-context/ (the agent-coordination directory; renamed to free the lowercase agents/ name)

v2.17.0 also migrates skill frontmatter to the metadata-nested structure per the agentskills.io specification and makes the CI validators bash-3.2 portable (macOS default bash). The 59-skill catalog is unchanged.

What’s changed

Native Claude Code sub-agent registration (LIVE)

Through v2.16.x, the sub-agent definitions lived in a subagents/ directory because the lowercase agents/ name collided with the repo’s then-uppercase AGENTS/ coordination directory on case-insensitive filesystems. v2.16.0 attempted to declare a custom path via a plugin.json field that turned out to be invalid (removed in v2.16.1), so native registration never actually worked.

v2.17.0 resolves it structurally: the coordination directory was renamed to _agent-context/, freeing the agents/ name, and the sub-agent definitions moved there. Claude Code’s plugin runtime auto-discovers agents/*.md at install time. Verified live on 2026-05-20: after /plugin update + /reload-plugins, all 4 sub-agents appear in the @-mention menu with their descriptions.

Frontmatter metadata-nested migration

All 59 skills moved phase, classification, version, and updated under the metadata: block, leaving only spec-recognized fields (name, description, license, metadata) at the top level per the agentskills.io specification. Validators and the doc-stack generators were updated to read the nested structure.

bash-3.2 validator portability

8 CI validators were rewritten to run on macOS default bash 3.2 (replacing mapfile/readarray and declare -A associative arrays, which are bash 4+ features). check-count-consistency gained a non-git-work-tree fallback so it degrades gracefully when run from the unpacked plugin install cache. check-version-references was wired into the pre-tag bundle as a non-blocking advisory step.

Migration guide

For the vast majority of users (installing pm-skills as a Claude Code plugin), no action is needed - the plugin runtime handles the new layout automatically. The notes below are for contributors, fork maintainers, and anyone whose tooling references pm-skills paths directly.

If you…Then…
Install pm-skills via the marketplace / /pluginNothing to do. Run /plugin update pm-skills + /reload-plugins; the 4 sub-agents auto-register.
Reference subagents/{name}.md in scripts or docsUpdate the path to agents/{name}.md.
Reference the AGENTS/ coordination directory in toolingUpdate to _agent-context/. The singular AGENTS.md discovery file at the repo root is unchanged.
Manually copied a sub-agent (e.g. to ~/.claude/agents/pm-critic.md)Re-copy from the new agents/pm-critic.md location.
Author or fork skillsNew skills must nest phase/classification/version/updated under metadata:. See an existing skills/*/SKILL.md for the shape.
Run the CI validators on macOSThey now run on the default bash 3.2 (no Homebrew bash 4+ required).

Why it matters

The dispatch-skill pattern always gave every client (Claude Code included) access to sub-agent behavior via the inline-execution path. But on Claude Code, native registration unlocks the ergonomic path: @pm-critic from the prompt, proactive invocation after PM-artifact skills, and the conductor’s native chain composition to the auditor and curator. v2.17.0 makes the dispatch skill descriptions (which already claimed native @-mention dispatch) true.

The frontmatter migration aligns pm-skills with the agentskills.io spec’s recognized field set, and the validator portability work means the /pm-skills:pm-audit-repo governance audit runs cleanly from the install cache on macOS.

What does NOT change in v2.17.0

  • Skill catalog (59 skills: 26 phase + 8 foundation + 10 utility + 15 tool) is unchanged.
  • Workflows (12) and slash commands (66) are unchanged.
  • The 4 sub-agents and 4 dispatch skills are unchanged in behavior; only their directory path changed.
  • Cross-client dispatch (Codex CLI validated at v2.16.0; Cursor / Windsurf / Copilot CLI / Gemini CLI via the dispatch skills) is unchanged.
  • Doc-stack (Astro 6.3.x + Starlight 0.39.x, Node 22.12+) carried forward.

Affected areas

AreaChange
agents/ (was subagents/)Sub-agent definitions relocated; natively auto-discovered. Phantom agents/README.md removed.
_agent-context/ (was AGENTS/)Agent-coordination directory renamed.
skills/*/SKILL.md (59)Frontmatter migrated to metadata-nested structure.
scripts/*.sh8 validators made bash-3.2 portable; check-count-consistency non-git fallback; check-version-references wired advisory into the pre-tag bundle.
.claude-plugin/plugin.json + marketplace.jsonVersion 2.16.2 to 2.17.0; descriptions refreshed.
README.md, CHANGELOG.mdVersion badge, What’s New, release-history, and changelog entry.
Doc-stack (docs/concepts, docs/contributing, docs/guides, docs/reference)Sub-agent docs updated for native discovery; obsolete custom-path rationale replaced.