agent-skills

Run the live testing phase after execute-plan ships a build — drive the spec's '### Post-ship verification' checklist (the human-gated ACs the diff can't prove) to pass/fail across three tiers: unit/frontend, real authenticated app, and server-log/DB. TRIGGER when: a shipped spec's Post-ship verification list needs behavioral testing; user says 'test the completed plan', 'run the testing phase', or 'verify the shipped spec'. SKIP for code review (use two-pass-review) or re-verifying code-gated ACs settled at the ship gate.

After finishing a coding task or plan, audit code comments and durable docs (CLAUDE.md, .claude/rules, ARCHITECTURE.md) for the changed files; propose scoped adds/updates/trims the user approves. Change-scoped, not a repo-wide doc sweep. TRIGGER when: user asks to update/sync durable docs, code comments, or CLAUDE.md after finishing work.

Implement a feature by executing its wave-grouped plan.md. TRIGGER when: user says 'run the plan', 'execute the plan', or 'implement it'; a plan.md has unchecked waves ready to build.

Keep a long execute-plan run alive across context windows: from a separate chat, watch the shared mailbox and respawn a fresh orchestrator whenever the run pauses at a wave boundary. TRIGGER when: user says 'supervise the plan run' or 'babysit the plan'.

Explain a feature, flow, or concept by grounding in source-of-truth, leading with the answer, and diagramming each load-bearing mental model. TRIGGER when: user says explain/walk me through/ELI5/help me understand; user wants to understand how a feature, flow, or system works. SKIP when: user wants a diagnosis/fix/action; user wants a one-line definition they can already apply; quick spot-check or confirmation.

Audit past Claude Code transcripts in a chosen scope and date window to extract reusable patterns, then walk through each one to promote it into a slash command, CLAUDE.md rule, memory entry, or new skill. Use when the user wants to retrospectively mine sessions for workflow improvements, recurring corrections, validated approaches, or repeated procedures worth capturing. Also counts how often a skill ran across past sessions.

Bounded resolver for confirmed P0/P1 findings. For each finding: fix → verify resolution via the verifier agent → up to 2 attempts → escalate. Scoped to per-finding resolution; regressions are the caller's job.

Research a project's design language and write or refresh a lean meta/DESIGN.md of facts — surfaces, toolkits, tokens, styling models, docs pointers — that grounds mockups and new UI. TRIGGER when: user asks to map, document, or bootstrap the design language, or to create/refresh meta/DESIGN.md; a skill needs grounding facts and meta/DESIGN.md is missing or stale. SKIP when: meta/DESIGN.md exists and is current (just read it); inventing a new aesthetic from a blank canvas (frontend-design).

Dispatch 1–3 subagents to analyze or verify something, then judge their findings yourself. TRIGGER when: user says 'multi-agent analysis', 'use subagents to analyze/verify', or 'dispatch subagents' to look into something.

Second opinion on one concrete proposal: stress-test it, rank alternatives, or both. TRIGGER when: user says 'second opinion', '2nd opinion', 'rate my fix', or 'weigh in on my approach'; user wants a candidate edit/decision evaluated. SKIP when: multiple decisions on a larger artifact — use `validate-answer`.

Analyze Sentry error logs, breadcrumbs, and codebase context to diagnose and explain the root cause of issues.

Two-pass code review: a `code-reviewer` pass followed by an adversarial `verifier` pass. Use for final review of completed code changes or any code review where a false positive would cost the user real time. Do NOT use for non-code artifacts or for quick spot-checks during iteration.

Surface what a draft, answer, or code is missing — parallel subagents each apply a different lens, scoring findings by impact and confidence, then walk them one at a time. TRIGGER when: user says 'find gaps', 'what did I miss', 'analyze from multiple angles', 'what am I overlooking'; user has an in-progress artifact and an open-ended mandate to improve it. SKIP when: building one answer (best-answer); trust-checking an answer you have (validate-answer).

Stress-test a plan, design, or decision — challenge assumptions, expose gaps, force specificity. TRIGGER when: user says 'grill me' or 'stress-test this'; user wants their plan or decision pushed on.

Verify a panel's findings against their artifact: each gets a consider / skip verdict and a confidence. TRIGGER when: a fan-out skill needs its findings verified before walking them with the user; user says 'triage these findings', 'verify which of these are real', 'which are worth acting on'.

The deep-module primitive: a small interface hiding lots of behaviour. Apply the lens to judge or shape one interface, or audit a codebase for shallow modules (returns a ranked table). TRIGGER when: user says 'deep modules', 'is this a deep module', 'find shallow modules', 'audit from the deep-module lens'; a skill needs the deep-module vocabulary.

Turn a locked product/UX spec into technical design — the HOW: architecture, data shapes, signatures, file layout. TRIGGER when: user asks how to implement a spec'd feature; user wants architecture, data-shape, or file-layout decisions; user says 'tech design' or 'design the implementation'.

Sequence a locked spec into dependency-ordered, wave-grouped tasks. TRIGGER when: user says 'build the plan' or 'sequence this'; a spec needs slicing into parallel-safe waves.

Socratically interview the user to move an open question — a decision, strategy, trade-off, or research direction — from ambiguity to clarity. TRIGGER when: user says 'interview me' or asks to be interviewed; user wants to think a decision or trade-off through Socratically; the topic is ambiguous and not a buildable feature meant to produce a spec.

Move from ambiguity to clarity on WHAT to build — product scope and UX — before any technical design. TRIGGER when: user says 'product interview' or 'design a new feature'; user wants product requirements, scope, or UX clarified before building; a feature's product/UX scope is vague.

Generate grounded UI mockups as self-contained HTML — PREVIEW a feature's screens, or COMPARE directions for one choice and pick — using the project's real design tokens. Fidelity is approximate by design, not pixel-perfect. TRIGGER when: you want a UI screen/flow rendered, or to compare 2+ visual directions you'd judge better by seeing than by ASCII; user says 'mock this up', 'show me the screens', 'show me the options', 'which looks better'. SKIP when: one direction is obviously right; the choice is logic/data/architecture, not visual; ASCII conveys it (AskUserQuestion preview); inventing one aesthetic from a blank canvas (frontend-design).

Audit one instruction file by composing the durable-instruction lenses over it — vet-fact (WORTH: does each fact earn a line?), place-fact (PLACE: is it in the right home?), tighten-instruction (SHAPE: tighten the line). Pick the subset the file needs: shape-only, worth+shape, or worth+place+shape. A misplaced fact can be relocated to its right home on your approval, or deferred for a durable-docs-update batch. TRIGGER when: user wants a skill file or durable doc (CLAUDE.md, a rule, ARCHITECTURE.md) audited for what to keep, where it belongs, and how it reads; user says 'refine/audit this file', 'prune and tighten this doc', 'what here is worth keeping'. For shape-only tightening, tighten-file is the leaner sibling.

File-level tightening pass on an instruction file (CLAUDE.md, skill, agent prompt, style guide) using `tighten-instruction` as the lens. TRIGGER when: user says 'tighten/simplify this file/skill/CLAUDE.md', 'cut this down'; user points at a verbose instruction file and wants it leaner.

Trust-check an answer, plan, or decision you already have — multiple identical independent reads converge per question, agreement signals confidence and splits flag what's contested, then walk each decision. TRIGGER when: user says 'validate', 'trust-check', 'is this right', 'pressure-test my decision'; user has a near-final answer or a few focused decisions to confirm. SKIP when: no answer yet, want one built (best-answer); surfacing what's missing (find-gaps).

Make an instruction line read cold: clarify it into plain words, then tighten it to one positive line. TRIGGER when: user says 'tighten/clarify this rule/fact', 'make this leaner/simpler/clearer', 'de-jargon this' in a skill, CLAUDE.md, agent prompt, or rule file.

Build the single strongest answer to one open question — a diverse panel of subagents attacks it, a clean-room judge maps their disagreement, then you synthesize one grounded answer better than any single take. TRIGGER when: user says 'best answer', 'fan out and synthesize', 'give me the strongest answer'; user has a hard question and no answer yet. SKIP when: validating an answer you already have (validate-answer); surfacing problems in a draft (find-gaps).

Compress the live conversation into minimal, copy-paste-ready handoff prompt(s) — context referenced by file path, not pasted — so a fresh chat picks up cleanly. TRIGGER when: user says handoff, handover, new-chat / fresh-chat prompt, prompt to continue or resume elsewhere; user asks for separate prompts to explore N different things in their own chats.

Route a kept fact to its durable home by delivery trigger and most-local-wins — across in-file comment, nested CLAUDE.md, path-scoped rule, root CLAUDE.md, ARCHITECTURE.md, or a skill. TRIGGER when: user asks 'where should this go', 'which file/rule/home does this belong in', 'is this in the right place', 'should this be a pointer'; placing or re-homing a fact already judged worth keeping.

Judge whether a candidate fact earns a durable-doc line: keep only what a future agent would get the wrong answer without; cut anything derivable from code, setup, breadcrumb, or a restated default. TRIGGER when: user asks 'does this belong in CLAUDE.md / a rule / the docs', 'is this worth keeping/writing down', 'should this be a comment'; vetting or pruning a fact before it's filed or shaped.

SDK reference for `@shopify/post-purchase-ui-extensions-react` — Shopify's post-purchase upsell surface (the screen between payment and the thank-you page). Distinct from modern `<s-*>` checkout-extensions, which have no post-purchase target. Use when writing/editing JSX for this package or looking up a post-purchase component's props. TRIGGER when: code imports `@shopify/post-purchase-ui-extensions-react`; user mentions post-purchase offer, post-purchase page, post-purchase upsell, post-purchase-ui-extensions, ShouldRender, applyChangeset, or `Checkout::PostPurchase::*`; user edits files under `extensions/*post-purchase*/`.

Routes Shopify Dev MCP calls for surfaces NOT covered by the bundled Shopify skills: `storefront-graphql`, `customer`, `partner`, `payments-apps`, `functions`, `hydrogen`, `liquid`, `custom-data`. SKIP for Admin GraphQL or App Home markup — the bundled `shopify-admin` and `shopify-polaris-app-home` skills cover those. SKIP entirely for `@shopify/post-purchase-ui-extensions-react` — the MCP doesn't index that legacy SDK; use `post-purchase-ui-extension` instead.

Load a personality archetype that shapes the agent's voice — greetings, status, closings, pushback tone — while keeping plans, diffs, and recommendations neutral. TRIGGER when: user says load a soul/personality/voice/archetype; user says give me a voice; user asks for a specific persona (e.g. gordon-ramsay, yoda); user says switch/swap/change soul; user says serious mode or resume personality.