Catalog

Extreme Programming for AI-human pair development. Use when: pair programming with your AI, building incrementally with tests, working with clear role division, or the user mentions XP/YAGNI/simple design/continuous refactoring.

Mandatory default entry point for any non-trivial build/add/fix/implement/refactor request — drives work through explicit spec-driven-development phases (constitution check → specify → clarify → plan → tasks → implement → verify/converge). Adapts GitHub spec-kit's workflow (github.com/github/spec-kit) onto existing harness skills instead of installing spec-kit's `specify` CLI — no new dependency, keeps the docs/specs/<date>-<slug>/ convention. Supersedes standalone /plan as the default path for multi-step or ambiguous work; /plan remains a valid sub-phase and stays directly invocable for planning-only asks. Skip for trivial edits (<3 files, mechanical). Use whenever the user asks to build/add/fix/implement/refactor anything non-trivial and no more specific composite (hotfix, incident-response, release-cut, merge-confidently, etc.) matches.

Analyze a problem, plan the fix, execute with verification. Use when tackling a non-trivial bug, feature, or refactor that needs structured approach.

Systematic root-cause analysis for bugs, errors, and unexpected behavior

Start-of-session routine — load context, check state, suggest next task. Use at the beginning of a fresh session or after a context reset.

Composite skill — emergency bypass of the release branch when production is broken and waiting for the next release-cut is not viable. Chains incident scoping → branch from main (NOT release) → minimal fix → pr-merge-readiness → merge to main → patch-version tag → deploy → cherry-pick to release branch → post-deploy verify (sentry + ci-watch). Use ONLY for production-impacting breakage; routine "small fix" work belongs in /pr-to-release.

Test-driven development — write tests first, implement second, refactor third

Meta-adder for toolkit artifacts. Single entry point to add a skill, pattern, best-practice, hook, agent, or guide with correct frontmatter + sync to 4 publish targets.

Auto-classify prompt complexity via Haiku (with heuristic fallback) and inject model routing hints for Agent tool calls. Wired as a UserPromptSubmit hook — fires on every prompt, routes low tasks to Haiku, standard to Sonnet, complex to Sonnet with thorough reasoning, and critical (security/arch/migrations) to Opus.

Build and debug Retrieval-Augmented Generation pipelines — chunking, embedding, retrieval, reranking

Aggregate every signal that gates a PR merge (CI, reviews, conflicts, branch staleness, security scans, third-party reviewers like CodeRabbit/Greptile/Sonar) into a single readiness verdict — MERGE / WAIT / FIX. Use as the one-call check before clicking merge instead of running ci-watch + gh-fix-ci + manual scan.

Test generation is repetitive but critical. Developers skip tests because writing edge cases is tedious. AI agents can generate tests quickly but often produce brittle, unrealistic tests that provide false confidence. Tests that mock internals, use fake data like "foo@example.com", or test implementation details break on every refactor.

Audit project gates (jest/vitest coverage thresholds, tsconfig strictness, eslint rules, husky/lint-staged, sonar quality gate, branch protection) and flag values mathematically incompatible with reasonable defaults for the project's app type. Surfaces conflicts BEFORE skills like test-cleanup or ship hit them. Use weekly, automatically, or before any major refactor.

Track and report token usage and estimated cost per session, agent, and phase

Composite skill — full production incident workflow from alert to post-mortem. Chains sentry (triage incoming events) → debug-deep (root cause) → incident-response (coordinate fix + comms) → ship-it (rollback or hotfix deploy) → adr-write (post-mortem). Use when production is on fire — not for dev-time debugging (use debug-deep alone for that).

Evaluate LLM outputs systematically — benchmarks, automated metrics, human preference, and regression tracking

Composite skill — research a question, challenge the conclusion, plan adoption, and capture the decision. Chains adt-research or brainstorming (explore) → critic agent (challenge) → plan (sequence) → adr-write (record). Use when evaluating a library / pattern / architecture choice — forces the research-to-ADR pairing that usually slips.

Default execution rhythm — inspect → act → verify → checkpoint — applied iteratively until the task is done or a clear blocker emerges. Use when working through a known plan, draining a queue (PRs, issues, dependency bumps), or executing a multi-step recipe where each step's output informs the next. Each iteration must produce a concrete artifact (commit, comment, decision) and a one-line state update. Stop on first unrecoverable error rather than retrying blindly. Pair with `ship` for merge-bound work and `handoff` if budget runs out mid-loop.

AI agents are fast at writing code but have no memory of your intent. You describe a feature in a prompt, the agent builds it, and three sessions later a different agent (or you) changes it in a way that drifts from the original requirement. The spec lives only in your head.

Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions (4.5 → 4.6, 4.6 → 4.7, retired-model replacements). TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project. SKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML.

Build a compact, validation-gated implementation plan for multi-step, risky, or ambiguous work — typically when phases need explicit checkpoints, the change touches multiple files/services, or the user wants alignment before execution. Output goes to `.claude/plans/<topic>.md` (or `.agents/plans/`) with goal, in/out-of-scope, phased steps, validation per phase, and replanning triggers. Skip for trivial single-file fixes, bug investigations (use `tracer`), or open-ended exploration (use `explore`). Pair with `ship` once the plan ends and merge work begins.

Fan out N independent investigations as parallel agents in a single tool-use block, then roll up the results. Use whenever the same question must be answered against multiple repos, PRs, or services.

Spawn parallel subtasks, assign to worker agents, collect results

Commit, push, and open a pull request with a conventional commit message

Prompt injection is not a theoretical attack. By Q1 2026, the benchmark is real: CaMeL achieves 67% injection block rate on AgentDojo. NIST AI RMF frames it as agent hijacking. Defense is not a single gate; it's depth.

Composite skill — land a safe first PR in an unfamiliar repo without rediscovery loops or guessing at conventions. Chains onboard-new-repo (architecture + scripts + CI scan) → context-pack (relevant files + standards + ADRs for the scoped change) → scope-and-execute (narrow the task) → test-driven-development (write failing test first) → pr-to-release (open the PR). Use the first time you contribute to a repo OR when an unfamiliar contributor needs a guided first change.

Implement features by dispatching a fresh subagent per task with mandatory two-stage review (spec compliance then code quality) after each task.

Diagnose and repair failing MCP servers. Captures real launch tracebacks, identifies stale tool/config references, prunes the bad entries, and reconnects. Use when `claude mcp list` shows `Failed to connect`, after upgrading an MCP server (Serena, @modelcontextprotocol/server-*, or vendor MCPs), or when an MCP that worked yesterday silently stopped responding.

Auto-extract reusable patterns from the current session into skills or memory

Validate live MCP provider health — separate config issues from auth and connectivity failures

Route a task to the most fitting skill or agent. Parses user intent, checks installed-skill inventory, and picks the best match (single skill or chain).

Read-only diagnostic that scans Claude Code session transcripts to surface which MCP servers and tools you actually use, ranked by call frequency, with zero-use servers flagged for removal. Use when planning an MCP cleanup, evaluating whether to keep a newly-added server, deciding which servers warrant token cost in the catalog, or before authoring an MCP-removal PR. Outputs a markdown report (last N days) — does not modify any settings. Pair with the manual `claude mcp remove <name>` step once findings are reviewed.

Persist decisions, preferences, and project state across sessions using structured memory types

Plan a code change before editing — identify files, sequence steps, set verification criteria

Recover session state from git, plans, and open PRs, then continue from the last completed phase without repeating work

Build robust, secure MCP servers — tool schemas, stateful interactions, async patterns, error handling, and testing

Shortcut for security review on current change set. Runs layered checks (secret-scan, dep-audit, semgrep, OWASP patterns, prompt-injection review).

Bump the ai-dev-toolkit version pin in a downstream consumer repo and verify the sync path

Assemble a Jira/Linear/GitHub-Issue body from recent commits, diff, and branch context

Check whether MCP-backed workflows are usable on this machine

Run full quality gate suite before committing or creating a PR

Choose and configure inference servers (vLLM, TGI, Ollama) — quantization, batching, scaling, and serving patterns

Optimize context window usage — compact stale data, compress via summarization, preserve active state

Decide when and how to use git worktrees for isolated parallel work

Composite skill — take a merged PR all the way to production. Chains version-bump → changelog-update → ship (tag + release) → deployment-automation or vercel-deploy / cloudflare-deploy / prod-rebuild → post-deploy verify (sentry + ci-watch). Distinct from merge-confidently which stops at merge; this one ends with "live in prod, verified, no incidents."

Decompose a task into parallel workstreams, assign agent ownership, run integration at dependency boundaries, and synthesize results.

Code review is time-consuming and inconsistent. Reviewers miss security issues, overlook edge cases, or focus on style over substance. Meanwhile, AI agents catch these mechanical issues instantly but can't judge business logic correctness, UX decisions, or architectural fit.

Composite skill — promote the long-lived `release` branch to `main`, cut a single version that batches every PR accumulated since the last tag, then clean up. Chains pr-merge-readiness (on release→main PR) → version-bump (semver from commits) → changelog-update (promote [Unreleased] → versioned) → ship (tag + GitHub release) → stale-branch cleanup → optional ship-it for deploy. Use this INSTEAD of releasing every small fix individually. Many small commits become one well-scoped release.

Inspect current CI state, identify the first real blocker, separate required failures from noise, and monitor until checks settle. Use when checks are failing, flaky, or blocking a merge.

Graceful degradation when primary approach fails. Try alternates in priority order; record which path succeeded for future routing.

Deterministic A–F grader for AI-generated code. Zero-LLM — regex/structure checks (anti-patterns, error handling, N+1, hardcoded secrets, sync I/O, index-as-key, a11y). Use right after any code generation, before ship-check; grade < C (score < 60) fails the gate. Ported from forge-space post-gen-scorer.

Optimize context usage for the session by reducing bloat, improving token efficiency, and focusing on relevant areas. Use when context is growing large, responses are slow, or switching between unrelated tasks. Covers context analysis, compacting, targeted pruning, MCP-first strategies, and focused scoping by area.

Deep research on a topic using web search, docs, and codebase analysis

Keep EN/PT README.md pairs in parity across a repo (and across twin repos like ai-dev-toolkit + ai-dev-toolkit-pt-br).

Define and manage recurring automated agent runs — CI monitoring, dep updates, security scans

UI/UX design system reference, pattern library, and focused review guidance for web and mobile applications. Use for targeted design research, pattern selection, UX audits, accessibility guidance, palette and typography selection, layout heuristics, and component pattern research. Covers 50+ styles, 97 color palettes, 57 font pairings, Web Interface Guidelines compliance, and concrete visual/usability improvements for modern SaaS and product interfaces.

Meta-skill codifying the no-wakeup-polling pattern. Describes the ScheduleWakeup anti-pattern, the fix (--auto merge + detached watcher), and when to still use wakeups. Reduces handoff spam by 80%.

Diagnose and fix macOS resource pressure for Claude Code workflows. Use when load avg is high, swap is saturated, CC feels slow, or before spinning up parallel agents/worktrees. Covers CPU top-talkers, swap pressure, zombie claude processes, Node heap tuning, Spotlight/background-agent pruning, and purge. Apple Silicon aware.

Capture an Architecture Decision Record — what was decided, why, what alternatives were considered, and when to revisit. Writes a numbered ADR file to docs/adr/ in the active repo, with consistent formatting that downstream skills (improve-codebase-architecture, refactor-plan) can read. Use right after deciding something non-obvious so the reasoning isn't lost.

Local build-error triage. Detects common compile errors and suggests fixes