agent-skills

Write an implementation plan to docs/plans/. ALWAYS use this skill — never hand-roll a plan by mimicking files in docs/. Use when the user wants to create a project/implementation plan, when a plan discussed in chat should be persisted, or says /project-plan. Guarantees a spec exists, invoking to-spec if absent. Decomposes into vertical slices with Blocked-by edges, points to the spec for acceptance criteria, and extracts ADRs via to-adr.

Parse test failure output and diagnose root causes in a read-only background subagent, then fix the failures interactively in the main thread. Use when the user shares test output or says "tests fail". Default output path is /tmp/output.

Surface systemic patterns from an investigation as codified conventions or anti-patterns.

Architect a change from idea to actionable artifacts — bootstrap project instructions, research deeply, write a spec, then an implementation plan, each delegated to its skill. Use when the user wants to research a topic, explore a repo, write a spec, create a project plan, or says /architect.

Research a topic or repository deeply and produce a reference document under `docs/research/`. Handles two modes: code research (repo by URL, `org/repo`, or bare name — e.g. "check the spotless repo", "look at github.com/fastly/spotless") and topic research (concepts, technologies, patterns). Use when the user wants to research something, explore a repo, or says /research.

Elicit the user's intent before starting work. Use when a request is vague, when kicking off a new task, when another skill hits a vague request and needs to clarify it, or when the user says "help me with this", "I need something", "let's work on...", "draft a task", or /task.

Produce a specification document at docs/specifications/ — problem, solution, user stories, acceptance criteria, testing seams, and scope for a feature. The engineering source-of-truth a plan later implements. Use when the user wants a spec or says /to-spec, or when another skill needs the spec phase before planning.

Continue working through a project plan. Finds the next unchecked task and begins implementation.

Generate Gherkin behavioural specifications (acceptance criteria) for a feature or plan. Feature/boundary scenarios become executable godog .feature files for Go; unit-level behaviour is captured as Given/When/Then prose. Returns scenarios plus scaffold tasks for the caller's plan. Use when the user wants BDD/Gherkin user stories, acceptance criteria, executable specifications, or says /behaviour-spec.

Extract a formal ADR (Architecture Decision Record) from an implementation plan or design doc — one ADR per genuine decision. Use when the user wants to record an architecture decision or says /to-adr, or when another skill needs to formalize a plan's decisions.

Extract a focused PRD (Product Requirements Document) — the product-facing what & why — from a spec or plan. Use when the user wants a PRD, product framing, goals and success metrics, or says /to-prd, or when another skill offers to produce one.

Make AGENTS.md the canonical project-instructions file and ensure CLAUDE.md and GEMINI.md are thin pointers that @-import it. Promotes existing CLAUDE.md/GEMINI.md content into AGENTS.md when AGENTS.md is missing or weaker, creates stub CLAUDE.md and GEMINI.md when absent, and bootstraps a fresh AGENTS.md when the project has no instructions file at all. Once canonical, also audits an existing AGENTS.md for structure drift, verifies its build/test/lint commands and gotchas are still accurate, and harvests durable lessons from the current session. Use when the user wants to tidy up agent instructions, onboard a project, check whether AGENTS.md is up to date, audit its structure, add what was learned this session, or says /agents-md.

Four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.

Branch, commit, and open a PR in one step. Creates a feature branch off the current base, commits the changes, then drafts and opens a pull request.

Create a git feature branch named for the current session's work. Slugifies the git username and derives a short kebab-case feature slug from the changes or task under discussion. Use when the user asks to start, create, or cut a branch.

Code review using specialized subagents. Analyzes consistency, idiomatic Go, data correctness, and security. Works on PRs or local code. Pass --plan or --plan=<path> to additionally check the diff against an implementation plan.

Create git commits with intelligent file grouping. Use when committing changes or drafting a commit message.

MANDATORY for any work on Go files (*.go). Load this before editing, reviewing, or creating any *.go file. Go coding conventions and style guide covering naming, error handling, testing, HTTP handlers, caching, concurrency, and observability.

Write unit and integration tests for Go services. Use when creating, editing, or updating tests, test helpers, mocks, fuzz tests, or benchmarks in Go projects.

Turn the current session's incident research/debugging into a report at docs/reports/. Use when the user has been investigating an incident or bug in a customer-facing service and wants it written up — "write an incident report", "document this incident", "write up what happened", "create a postmortem", or /incident-report. Captures what broke, when, customer impact, root cause, and mitigations/long-term fixes.

Add a new entry to the project's CHANGELOG.md based on uncommitted diff or branch-vs-main changes. Use when the user asks to update the changelog, add a changelog entry, or record changes.

Review codebase for AI slop and clean it up. A read-only subagent audits files and produces a proposed fix list; the main thread then applies fixes interactively so you can steer each one.

Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation

Multi-agent deliberative workflow for non-trivial tasks — assess, review, discuss to consensus, implement, re-review, with round caps and surfaced dissent. Only after the user has explicitly confirmed it for the current task. Suitable for architectural changes, multi-file features, unclear-root-cause bug investigations, design decisions, behavior-changing refactors. Skip for typos, single-line fixes, comment-only edits, formatting, renames, or throwaway snippets.

Critique a document for logical fallacies and weaknesses. Identifies issues and provides actionable fixes.

Decision Memo + Contrarian Check. Runs an interview, structures the options with explicit assumptions, dispatches a contrarian pass to find holes and second-order effects, and produces a saved decision memo with a clear recommendation and reversibility rating.

Spawn an appropriate subagent to handle a task.

Rewrite text to be more concise, clear, and direct without losing critical information. Inventories load-bearing details first, rewrites, then audits the rewrite to verify nothing essential was dropped. Use to clean up a plan, technical guide, agent instructions, or any prose that is too long or hard to follow — especially before handing it to an agent to execute. Triggers on "clean up / tighten / condense / distill this", "make this more concise without losing detail", or /distill.

Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.

Draft a concise, direct pull request with a clear Problem and Solution. Use when the user asks to create, draft, or open a PR.

Convert Markdown files from a directory into agent skills.

Strategic codebase-wide audit for aspirational redesign opportunities. Hunts for "code judo" moves that delete whole categories of complexity, drift from documented standards, drift from stated purpose, and gaps in test coverage that would make a redesign unsafe. Produces a phased redesign plan with mandatory test-pinning before any structural change.

Analyze an existing feature and produce a reimplementation plan focused on reducing complexity and fragmentation. Asks: "If we started over, what would we do differently?"

Use when receiving a security review or vulnerability report — from an AI tool, a security-review command, or a human reviewer — and deciding which findings are real and worth fixing. Verify reachability, attacker control, and exploitability before implementing any fix; reject false positives and severity inflation rather than agreeing reflexively.

Translate an engineering plan doc or branch diff into a non-engineer-friendly summary for a PR description, Slack update, or email. Output is copy-paste only — nothing is written to the repo.

Teach the user a new skill or concept, within this workspace.

Write or improve technical documentation. Applies documentation best practices: brevity, eliminating assumptions, modularization, visualization, and reducing stale code references. Use when writing new documentation from scratch, or editing, or reviewing and rewriting existing documents for clarity and quality.

Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

Compact the current conversation into a handoff document for another agent to pick up.

Audit a codebase for MySQL index correctness. Finds composite indexes broken by leftmost-prefix violations, queries that only partially use an index (index gaps), and index killers (leading wildcards, function-wrapped columns, type mismatches). Static analysis of schema + query code; reports EXPLAIN follow-ups.