Skills are model-invoked based on the description in their frontmatter — Claude reads the descriptions of every available skill at session start and picks one when the user's request matches. The plugin's UserPromptSubmit hook adds a reminder banner that nudges Claude toward the right skill for each classified prompt kind.

How hooks compose

UserPromptSubmit runs every turn before Claude reads the user's message. Returns JSON with hookSpecificOutput.additionalContext — that string is invisibly appended to the prompt Claude sees.
PreToolUse with matcher: "mcp__github__create_pull_request" only fires when that exact MCP tool is called. Returns decision: "block" to halt the call with a reason (no PR is created).
Stop runs at end-of-turn. Outputs to stderr only — non-blocking.

How `lib/validate-evidence.sh` works

Reads an evidence markdown blob (the comment the agent is about to post on the issue) and verifies:

Every required ## Section is present
Each section has at least 10 chars of content
Sections marked require_file_paths contain at least one path that exists in the repo

Output is JSON — the calling skill parses it and either proceeds or surfaces the errors verbatim.

Local development

bash

Versioning

plugin.json declares "version": "0.1.0". Bump on every release so users get an update prompt; omit version to use commit SHA (continuous delivery).

Tests

Unit-test the lib scripts with bats (brew install bats-core):

bash

Roadmap

v0.1 — labels, templates, 12 skills, 3 hooks, gate validation
v0.2 — .github/gh-pms.yaml per-repo overrides
v0.3 — GitHub Project (kanban) integration via gh project
v0.4 — multi-repo plans (cross-repo sub-issues)
v0.5 — gh-pms-stats skill: cycle time, gate failures, WIP heatmap

Plugin layout

How skills get invoked