docs(contributing): teach authors to run apm-review-panel + pr-description-skill locally#1057
Merged
danielmeppiel merged 3 commits intomainfrom Apr 29, 2026
Merged
Conversation
…ption-skill locally External contributors hit the panel verdict on PR for the first time and treat 'required' findings as a surprise instead of a checklist they could have run pre-push. Document the two highest-leverage skills (.github/skills/pr-description-skill for the body, .github/skills/apm-review-panel for the verdict), the typical 4-step local flow, and that single personas under .github/agents/ can be summoned for focused reviews. Skill bundles work in any SKILL-compatible harness (Claude Code, Copilot CLI, Cursor, OpenCode, Codex, Gemini), so this is harness-agnostic guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates contributor guidance to encourage running the repo-shipped review/authoring skills locally (the same rubric CI applies) before opening a PR, to reduce back-and-forth after CI verdicts.
Changes:
- Adds a new CONTRIBUTING section describing when/how to run
apm-review-panelandpr-description-skill. - Documents a suggested local authoring flow (implement -> panel -> PR body draft -> push/PR).
- Points contributors to
.github/agents/personas for focused, single-expert reviews.
Show a summary per file
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds a new section teaching contributors to run the repo’s review/PR-authoring skills locally before pushing/opening PRs. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 4
| | Skill | When to use it | | ||
| |---|---| | ||
| | [`.github/skills/pr-description-skill`](.github/skills/pr-description-skill/SKILL.md) | **Every PR.** Drafts a self-sufficient PR body (TL;DR, Problem / Approach / Implementation, mermaid diagrams, validation evidence, How-to-test) that anchors every WHY-claim to PROSE / Agent Skills. Avoids the "what does this PR even do?" round-trip. | | ||
| | [`.github/skills/apm-review-panel`](.github/skills/apm-review-panel/SKILL.md) | **Non-trivial PRs** (new behaviour, security-relevant code, CLI UX changes, manifest/schema changes). Runs the same multi-persona panel CI runs in `pr-review-panel.yml` -- locally, before you push. Surfaces the `required` findings while the cost of fixing is still cheap. | |
There was a problem hiding this comment.
pr-review-panel.yml does not appear to exist in .github/workflows/ (the panel workflow is pr-review-panel.md with a generated pr-review-panel.lock.yml). Update this reference so contributors can find the CI workflow you mean.
Suggested change
| | [`.github/skills/apm-review-panel`](.github/skills/apm-review-panel/SKILL.md) | **Non-trivial PRs** (new behaviour, security-relevant code, CLI UX changes, manifest/schema changes). Runs the same multi-persona panel CI runs in `pr-review-panel.yml` -- locally, before you push. Surfaces the `required` findings while the cost of fixing is still cheap. | | |
| | [`.github/skills/apm-review-panel`](.github/skills/apm-review-panel/SKILL.md) | **Non-trivial PRs** (new behaviour, security-relevant code, CLI UX changes, manifest/schema changes). Runs the same multi-persona panel CI runs in `pr-review-panel.lock.yml` -- locally, before you push. Surfaces the `required` findings while the cost of fixing is still cheap. | |
| items in-place. | ||
| 3. Ask your agent: *"Use the pr-description-skill to draft the PR body | ||
| for this branch."* Review the draft, paste it into `gh pr create | ||
| --body-file`. |
There was a problem hiding this comment.
gh pr create --body-file requires a file path argument; as written, the command is incomplete and will confuse first-time contributors. Consider showing a concrete example (or a placeholder like <path-to-body.md>) so it's copy/pasteable.
Suggested change
| --body-file`. | |
| --body-file <path-to-body.md>`. |
Comment on lines
+33
to
+34
| ### Author your PR with the agent skills shipped in this repo | ||
|
|
There was a problem hiding this comment.
This section replaced the previous ### Development Process heading, but the generic contribution steps (starting with "1. Fork the repository.") now immediately follow without any heading. Reintroduce a ### Development Process (or similar) header before the fork/branch/test steps so the document structure stays clear.
Comment on lines
+33
to
+40
| ### Author your PR with the agent skills shipped in this repo | ||
|
|
||
| This repo ships its own review and authoring skills under `.github/skills/` | ||
| and the personas they call under `.github/agents/`. They run in any | ||
| SKILL-compatible coding agent harness (Claude Code, GitHub Copilot CLI, | ||
| Cursor, OpenCode, Codex, Gemini, etc.) -- no extra install, just clone | ||
| this repo and let your harness discover the bundle. | ||
|
|
There was a problem hiding this comment.
This content appears to be duplicated in the Starlight docs page docs/src/content/docs/contributing/development-guide.md (which still has a ### Development Process section and does not mention these skills). To avoid contributor guidance drifting, update that docs page (or link it to CONTRIBUTING.md) to reflect this new "author your PR" workflow.
…t the skills Previous wording said 'no extra install, just clone' -- wrong. The skills live under .apm/ (canonical primitive layout); .github/skills/ etc. are deployment outputs. Contributors must run apm install after checkout to have their harness pick up the bundle. Rewrite the section to lead with 'APM dogfoods APM', show the install + apm install commands, and update all skill links to point at the canonical .apm/ paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a 'When to summon which persona during design and implementation' subsection so contributors consult the right specialist while building instead of discovering the gap from the panel verdict. Hard rules: - devx-ux-expert validates UX of new features BEFORE implementation - cli-logging-expert is always included for any terminal output - python-architect for refactors / non-trivial architecture - supply-chain-security-expert is MANDATORY for anything touching apm install / fetching / scanning / locking -- non-negotiable, this is a core promise of APM - auth-expert for any auth / token / credential change - apm-primitives-architect for primitive or manifest schema changes - doc-writer / oss-growth-hacker for public-facing copy Pattern: critique the plan with the persona, then review the diff with the same persona. Two cheap focused passes beat one panel rejection. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Teach external contributors to run the same review skills CI runs, before pushing. Two skills get a top-level section in
CONTRIBUTING.md:.github/skills/pr-description-skill— for every PR, drafts the anchored, concise body the maintainer review expects..github/skills/apm-review-panel— for non-trivial PRs, runs the multi-persona panel locally sorequiredfindings get fixed in-place instead of after the CI verdict comment lands on the PR.Why
Context: #1039 is an excellent contribution from an external author. They saw the panel verdict (10
requiredfindings) for the first time after opening the PR, which reads as gatekeeping. The skills already encapsulate the rubric the panel applies — but they're invisible fromCONTRIBUTING.md. Once a contributor knows they exist and how to run them, the panel becomes a self-service checklist instead of a surprise.What changed
One new subsection under "How to Contribute":
.github/agents/*.agent.mdpersona can also be summoned standalone for a focused review.Trade-offs
CONTRIBUTING.md— worth it; this is the first thing an external contributor reads.How to test
CONTRIBUTING.md— does the 4-step flow make sense to someone who has never seen.github/skills/before?Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com