rosslevinsky/portable-agent-skills

Explains the thing the user is asking about in plain, jargon-free English, straight from its source — this conversation, pasted text, a document, code, a term, or a link. No repository required. With no argument, explains the last response. Use when the user invokes /clarify, or says "I don't understand this", "explain that again, more clearly", "what do you mean by X", "I didn't follow that", "unpack this", or "demystify".

Stage the paths a change touched — named, never a git add -A sweep of the tree — then write a descriptive commit message based on a diff review and commit. Pushes only when the request asked to publish: "commit and push" or "push my changes" push; "stage and commit" or a bare /commit stop at the commit. Use when the user invokes /commit, or says any of those. Optional argument: a list of specific files/paths to stage instead.

Multi-pass review of recent work to catch errors, gaps, and improvements. Use when the user invokes /cyw, or asks to 'check your work', 'review what you just did', 'is this correct/complete?', 'what's missing?', 'what needs fixing?'. Runs a structured 3-phase loop: critical review, fix, verify. Repeats up to 3 times, stopping early when no issues remain. Supports an embedded single-pass mode (argument: single-pass) for use inside phase gates.

On-demand guided-tour walkthrough video of a built feature — the last skill in the v2 workflow. Drives an existing Playwright / frontend setup through the primary flow slowly with pauses, records video, and derives timed subtitles from as-built.md and test-step timing; optional background music. Never bootstraps Playwright and never claims success from "a video exists" alone. Without ffmpeg it still ships Playwright's native video plus a sidecar subtitle file; it degrades to ordered screenshots only when no video can be recorded at all. Narration audio is out of scope — it writes subtitles, not speech. Use when the user invokes /demo-video, or says "make a demo video", "record a walkthrough", "generate a guided tour of the feature".

Independent, diff-first code review of a change set. A dedicated reviewer reads the diff first with fresh context — no reliance on the implementation rationale — and reports correctness findings without editing the tree. Distinct from author self-review: it is the second, adversarial pair of eyes at a phase or PR boundary, focused on whether the code is actually correct. Use when the user invokes /diff-review, or says "review this diff independently", "do an independent code review", "review the branch before I merge".

Audit TSX files, identify non-UI logic, and extract it into custom hooks. Use when the user invokes /extract-hooks, or says "extract hooks", "move logic out of components", or "separate logic from layout".

Iterative plan refinement between Claude and Codex. Each agent writes an initial plan using a condensed v2 plan methodology embedded in the skill (mirroring plan-init's content model), then they alternately critique and incorporate the other's best ideas, with a judge checking for convergence after each round. Three exits: convergence (score ≥8/10, from round 3 onward), stagnation (no score improvement over 3 consecutive rounds), or the 10-round cap. Writes a summary.md with a score trajectory, a pointer to the winning plan, and a breakdown of remaining differences with pros/cons. Supports resume from an interrupted run. Use when the user invokes /plan-duel, or says "duel the plans", "run plan duel", "cross-compare plans with codex" — the input is a problem statement the skill generates competing plans from, not two existing plans to compare against each other. Argument: the problem statement (inline text or a file path), or the path to an existing plan-duels workdir to resume.

Create a structured project plan document for a task — the current planning suite. Interviews the user to fill gaps, explores the codebase, then produces a master plan.md stamped with the Format: v2 marker and a Suite row, and — when the plan lives under plans/ — registers it in the plans/README.md discovery index. Stays breakdown-unaware (work breakdown is /plan-phase's job) and adds UI-verification success criteria when UI is in scope. Use when the user invokes /plan-init, or says "make a plan", "create a plan", "plan this out", "let's plan before we start".

Create a plan document using the superseded v1 workflow — it writes no Format: v2 marker and no execution.md tracker. Use when the user invokes /plan-init-v1, or is continuing an existing v1 plan; new work belongs to /plan-init. Interviews the user to fill gaps, explores the codebase for context, then produces a master plan with goal, success criteria (checkable tests/conditions), technical constraints, non-goals, and affected areas. Does NOT break the plan into phases — use /plan-phase-v1 for that.

Work breakdown for a plan — the current planning suite. Reads a Format: v2 plan.md, proposes an ordered phase list (noting in prose which phases are independent and which reconciles them), then writes one phase document per phase plus the checkbox execution.md tracker (never phases.md). UI phases get a spec item and a visual-verify gate box; every phase carries a compact evidence record. Use when the user invokes /plan-phase, or says "break this plan into phases", "WBS the plan", "create the execution.md tracker".

Work breakdown for a superseded v1 plan — it writes phases.md, not execution.md. Use when the user invokes /plan-phase-v1, or is continuing an existing v1 plan produced by /plan-init-v1; a plan carrying the Format: v2 marker belongs to /plan-phase. Reads the plan document and breaks it into ordered phases, proposes the phase structure to the user for approval, then creates a phase document (with checklist) for each phase and writes a new phases.md execution tracker alongside the plan. The original plan document is never modified.

Execute a plan produced by /plan-init + /plan-phase — the current planning suite. Reads plan.md + the execution.md checkbox tracker + the current phase doc (never phases.md), and runs phases in order, resuming from the first unticked box and re-reading that phase document before executing it. Runs the per-phase gate (scoped tests + web-verify for UI + a single-pass cyw author review + diff-review, cross-runtime when a second runtime is available, on any diff with reviewable code), fills each phase's evidence record, makes at most one commit of its own work per phase, and assembles an as-built.md drift report. Refuses a plan that carries no Format: v2 marker. Use when the user invokes /plan-run, or says "execute the plan", "run the plan", "continue the plan".

Execute a superseded v1 plan — one driven by phases.md rather than execution.md. Use when the user invokes /plan-run-v1, or is continuing an existing v1 plan produced by /plan-init-v1 + /plan-phase-v1; a plan carrying the Format: v2 marker belongs to /plan-run. Reads the master plan and phases.md execution tracker, identifies incomplete phases, and executes each phase in order: checks entry criteria, completes tasks, runs verification, runs /cyw, reviews the staged diff, commits and pushes to origin, then marks the phase done in docs. Updates phases.md status block throughout. Skips already-completed phases so it is safe to restart.

This skill should be used when the user asks to 'security review the codebase', 'audit the codebase for vulnerabilities', 'run a full security audit', 'run a deep, thorough, or hierarchical security review', or 'check the whole project for security issues' — any security review scoped to the entire checked-in codebase (not uncommitted changes, not general code quality). Runs a single-pass audit by default and scales to an optional hierarchical deep mode (per-component sub-reviews plus a cross-component data-flow pass) for large or complex codebases — per-component reviews run as sub-agents where available, sequentially otherwise.

Test-driven development workflow. Enforces red/green/refactor discipline: write failing tests first, implement the minimum code to pass, then clean up. Use when the user invokes /tdd with a feature to implement (e.g., "/tdd implement the vocab export endpoint", "/tdd add useMyHook"). Never skips ahead to implementation before confirming tests fail.

Screenshot-first visual and behavioral verification of a running web UI. Use after building or changing UI to confirm it actually renders and behaves correctly — not just that unit tests pass. Detects an existing Playwright / frontend setup and drives it to capture screenshots (and, optionally, ffmpeg-extracted video frames), then inspects the images against anchored assertions. Never bootstraps Playwright into a repo that lacks it — it degrades to a manual UI-verification checklist. Use when the user invokes /web-verify, or says "verify the UI", "check it renders", "visually verify", "screenshot the app and confirm it works".