skills

Use when the user wants to research, review, or enhance an agent skill on a regular cadence — weekly skill uplift, audit a SKILL.md against best practice, compare with popular external skills, fix working issues, or align with agentskills.io. Triggers on "review this skill", "enhance the X skill", "weekly skills review", "uplift this skill", "align with agentskills.io". Works on one skill or a batch. Do NOT use to create a skill from scratch (create-skill / author a new skill), route which skill to use (skills-index), or review product documentation (docs-review).

Use when the user wants ADR register planning, writing ADR-NNNN files, or ADR review under docs/architecture/decisions/. Triggers on "do we need an ADR", "write ADR-0007", "record this decision", "what decisions need making", "harvest ADRs from this epic". Do NOT use for full architecture narrative (solution), epic design (design), or product strategy (product). Proposals stay in register.md only until accepted.

Use to groom an existing backlog or judge whether a breakdown is ready to commit to — reprioritise, split oversized epics or stories, re-estimate, defer misaligned items, and check sprint readiness of docs/product/backlog.md or docs/work/{epic}/tasks.md. Triggers on "groom the backlog", "refine the backlog", "is this sprint-ready", "are these stories ready", "reprioritise", "this epic is too big", "clean up the backlog". Amends in place and reports a verdict. Do NOT use to create a backlog or write new stories and tasks (tasks), plan a sprint (sprint-planning), review a finished sprint (sprint-retro), or verify an epic against its acceptance criteria (validate).

Use when the user wants to address, action, or fix findings from a code review — their own working diff reviewed by code-review, a reviewer's comments on a PR or MR, or a pasted list of issues. Triggers on "fix the review findings", "address the review feedback", "action the blocking issues", "apply the review comments". Optionally scoped to an action tier (blocking, warning, all). Makes targeted, behaviour-preserving changes, runs the project's validation suite, and commits in logical units. Do NOT use to perform a review (code-review), to implement new work or features (implement), to address UX or design-fidelity findings (ux-design-review), or to open a PR/MR (merge-request).

Use when the user wants a code review of a branch, PR, MR, or working diff against its acceptance criteria and declared scope, in whatever form they take in this repo. Triggers on "review my branch", "review this PR", "check this diff before I raise it", "is this ready to merge". Works with any language, delivery process, or issue tracker. Produces a structured verdict with blocking, warning, and suggestion findings; writes no source changes. Do NOT use to address or fix review findings (code-review-fix), to implement work (implement), to publish a review to a provider as its reviewer (merge-request-review), to sign off completion of a larger body of work (validate), or to review rendered UI (ux-design-review).

Use when the user wants epic-level technical design at docs/work/{epic}/design.md, walking-skeleton or TDD design, or design review before tasks. Pass epic slug or ID (CHK01). Cite solution.md — do not re-narrate architecture. Triggers on "design CHK01", "write the epic design", "how should we build this epic", "review the design before tasks". Do NOT use for epics or stories (tasks), task Gherkin (tasks), system-wide architecture (solution), ADR write (adr), code implementation (implement), or reviewing a set of documents for quality and consistency (docs-review).

Use when the user wants a set of documents reviewed — a docs folder, a wiki, a handbook, a repo's markdown, or any collection of written material. Checks that each document is well written and well structured, that boundaries between documents are clear with no duplication, and that the set is consistent and cohesive. Triggers on "review the docs", "are these docs any good", "is our documentation consistent", "do these docs overlap", "audit the documentation". Works on any doc set in any format or tool. Read-only: produces a report and changes nothing. Do NOT use to write or amend a document, to review code (code-review), or to review rendered UI (ux-design-review).

Use when the user wants to implement a task in code against an approved design.md and docs/work/{epic}/tasks.md. Triggers on "implement CHK01-01", "build this task", "write the code for this story". Reads the design and acceptance criteria, writes code and tests, runs the project's full validation suite, and commits in logical units. Do NOT use for code review (code-review), addressing review feedback (code-review-fix), changing how existing UI looks or behaves (ux-design-fix), writing tasks (tasks), or writing a design (design).

Use when the user wants an already-open merge request or pull request driven to a merge-ready state — watching CI, fixing objective check failures, triaging review threads, and syncing merge conflicts until all checks are green and nothing is unresolved. Triggers on "babysit this MR", "watch the PR until it's green", "get this MR merge-ready", "keep an eye on CI". Works with any codebase and any git provider — GitHub, GitLab, or Bitbucket — using MCP tools where available, provider CLIs otherwise. Never merges. Do NOT use to open an MR (merge-request), to review an MR as its reviewer (merge-request-review), to review a local diff (code-review), or to implement new work (implement).

Use when the user is the reviewer of a merge request or pull request and wants it reviewed and the verdict published to the provider — inline comments on the right lines, threads resolved or replied to, and an approve / request-changes / comment decision. Handles first reviews and re-review rounds after the author pushes. Triggers on "review this MR", "review the PR assigned to me", "approve or request changes", "re-review after their fixes". Works with any codebase and any git provider — GitHub, GitLab, or Bitbucket — using MCP tools where available, provider CLIs otherwise. Do NOT use to review your own working diff before opening an MR (code-review), to open or babysit an MR (merge-request), or to implement changes (implement).

Use when the user wants to open a merge request or pull request for the current branch, with a generated title, description, labels, and reviewer suggestions. Triggers on "open a PR", "raise an MR", "create a pull request", "put this branch up for review". Resolves change context and provider, discovers the repo's MR/PR template, composes a size-adaptive description, pushes, and creates the MR. Works with any codebase and any git provider — GitHub, GitLab, or Bitbucket — using MCP tools where available, provider CLIs otherwise, and plain git as a last resort. Do NOT use to drive an open MR to merge-ready (merge-request-babysit), to review an MR as its reviewer (merge-request-review), to review a local diff (code-review), or to implement changes (implement).

Use when the user wants a product strategy doc, PRD, pitch, vision, personas, or outcomes at docs/product/product.md. Two modes: write (draft or re-author) and review (critique, update for currency, amend in place). Triggers on "write the PRD", "draft a product pitch", "who are our personas", "review the product strategy", "is this strategy still current". Do NOT use for phased delivery plan (roadmap), epics or backlog (tasks), architecture (solution), tasks or Gherkin (tasks), or implementation (implement).

Use to seed or configure a Ralph loop before running it: choose a preset (engineering delivery for an epic, ad-hoc for a single repeating prompt, or custom steps), resolve the environment, set the completion promise and iteration budget, and write the loop files. Triggers on "set up a ralph loop", "configure a ralph loop", "ralph-loop-setup", or naming an epic to loop over. Do NOT use to start, inspect, or stop a loop (ralph-loop) — setup never executes loop steps.

Use to start, inspect, or stop a Ralph loop: an autonomous self-referential loop where a stop hook re-feeds the same prompt every turn until a completion promise is emitted or a safety rail fires (ralph-loop start, ralph-loop status, ralph-loop cancel). Works for any repeating multi-step job via presets, including full epic delivery through implement, review, validate, and merge request. Do NOT use to seed or configure a loop (ralph-loop-setup), implement a single task once (implement), review a diff (code-review), or sign off an epic (validate) — the loop orchestrates those skills.

Use when the user wants outcome-based delivery phases, exit criteria, or roadmap review at docs/product/roadmap.md. Two modes: write (draft or re-sequence) and review (judge credibility, record delivery evidence, amend in place). Triggers on "build the roadmap", "what are our delivery phases", "phase exit criteria", "is this roadmap credible", "did we hit the phase gate". Requires product.md for write. Do NOT use for epic breakdown or work paths (tasks), PRD (product), per-epic design (design), tasks (tasks), or architecture detail (solution).

Use when the user asks which skill to use, how to start delivery, or what to do next without naming a skill. Routes to product, backlog, tasks, design, etc. Triggers on "which skill should I use", "what can I do here", "how do I start", "what's next", "where do I begin". Do NOT produce artefacts or implement code — only recommend skill and mode.

Use when the user wants to write or review system architecture at docs/architecture/solution.md (stub or full arc42-lite). Triggers on "write the architecture", "solution design", "arc42", "review the architecture", "does solution.md match what we built". Do NOT use for business strategy (product), delivery phases (roadmap), epic list (tasks), per-epic design.md (design), task Gherkin (tasks), or ADR files (adr write). Story AC belongs in docs/work/{epic}/tasks.md.

Use when the user wants to plan a sprint before it starts — set the sprint goal, pull committed scope from the backlog and epic tasks.md files, account for carry-over and capacity, and record dependencies, risks, and the sprint definition of done at docs/work/sprint-{id}/plan.md. Triggers on "plan sprint 3", "what should we commit to", "set up the next sprint", "sprint planning". Do NOT use to review a finished sprint (sprint-retro), write stories or task Gherkin (tasks), groom the backlog (backlog-refine), re-sequence delivery phases (roadmap), or sign off an epic (validate).

Use when the user wants to run a retrospective after a sprint ends — compare what was committed in plan.md against what actually shipped, surface themes with evidence, and record actions with owners routed to the skill that will action them, at docs/work/sprint-{id}/retrospective.md. Triggers on "run the retro", "sprint retrospective", "what went wrong last sprint", "how did sprint 3 go". Do NOT use to plan the next sprint (sprint-planning), sign off an epic against its acceptance criteria (validate), run a cross-document alignment pass (docs-review), or review a diff (code-review).

Use to decompose anything into delivery work — a product strategy and roadmap into epics, an epic or its design into stories and tasks with Gherkin acceptance criteria, or an external spec, RFC, or PRD into both in one pass. Writes docs/product/backlog.md and docs/work/{epic}/tasks.md. Triggers on "break this spec into a backlog", "write the epics", "decompose checkout-foundation", "turn this RFC into tickets", "write tasks for CHK01", "what stories do we need". EARS with --ears. Do NOT use to groom an existing backlog or check sprint readiness (backlog-refine), write epic design (design), write architecture (solution), phase the delivery (roadmap), implement code (implement), or sign off an epic (validate).

Use when the user wants to change how existing UI looks or behaves — fix spacing, colour, layout, states, responsiveness, or accessibility on a component, page, or flow. Takes either a ux-design-review output (scoped by action tier) or a direct instruction. Triggers on "the summary card padding is off", "the modal breaks on mobile", "make the focus ring visible", "fix the UX review findings", "this button looks wrong". Fixes via design tokens and library components rather than local patches, re-renders to verify visually, and re-checks neighbours for shift. Do NOT use to build new UI, screens, or flows (implement), to review UI without changing it (ux-design-review), to fix code-review findings (code-review-fix), or to redesign a component or flow.

Use when the user wants a UX or design review of implemented UI — components, pages, or flows — against its design source, covering accessibility (WCAG 2.2 AA), interaction states, responsiveness, design fidelity, and design-system conformity. Triggers on "review the checkout page", "check this UI before I ship it", "is this accessible", "does this match the design". Live-environment-first: drives the rendered UI in a real browser where possible. Works with any framework or design tooling. Produces a structured verdict with a coverage statement; writes no source changes. Do NOT use to address or fix UX findings (ux-design-fix), for code correctness or security review (code-review), to review a design.md document (design), or to implement features (implement).

Use when the user wants final epic completion sign-off: every task in docs/work/{epic}/tasks.md verified against Gherkin AC and roadmap phase exit criteria. Triggers on "validate CHK01", "is this epic done", "sign off the epic". Builds an acceptance matrix with evidence, updates task and epic status, and produces a validation report. Do NOT use for PR or branch code review (code-review), writing tasks (tasks), sprint retrospective (sprint-retro), or drafting the breakdown (tasks) or design.

Replace with description of the skill and when the agent should use it.