Agent Skills

Skills and agents for AI coding assistants — autonomous workflows, code review, TDD, UX, DX, debugging, and more.

A curated collection of skills, slash commands, and agents that encode how I actually ship software — distilled from real projects, not theory. They take a holistic approach to building and debugging, with three throughlines:

• Autonomy — workflows that carry a task from a one-line prompt to a tested, reviewed PR (autonomous-workflow, fix-bug).
• Product building — UX, visual design, and analytics treated as first-class, not afterthoughts (ux, visual-design, charting, rum-tracking).
• Quality — confidence gates, adversarial pre-mortems, and TDD baked into the loop, not bolted on after (confidence, critical, tdd, code-quality).

Works with Claude Code, Cursor, Codex, Gemini CLI, Copilot, Windsurf, OpenCode, and any other Agent Skills-compatible tool.

git clone https://github.com/mthines/agent-skills.git
cd agent-skills && bash scripts/sync-symlinks.sh

Symlinks every skill live into your tool — edits and git pull land on the next agent turn, no reinstall. Upgrading, customizing, and the no-clone npx path are in Install.

---

Table of contents

• Skills at a glance
  • workflow/ — end-to-end orchestrators
  • quality/ — code, tests, plans, AI apps
  • delivery/ — Git, PR, CI
  • testing/ — E2E and fixture tooling
  • design/ — UI, visual, interaction
  • analysis/ — investigate data, diagnose issues
  • authoring/ — skills about Claude Code itself
• Agents at a glance
• Featured: autonomous workflow
• Usage examples
• Install
  • Recommended: clone + symlink
  • Upgrading
  • Customize and still track upstream
  • Quick try: npx skills add
• VS Code extension
• Linear ticket investigator (per-project plug-in)
• Repository structure
• Local development
• Contributing
• License

Skills at a glance

Skills are grouped by directory category. Each row shows the invocation type:

• auto — model-invokable via Skill(). Description sits in your available-skills list every session (~50–150 tokens); body loads only on invocation.
• / — slash command only. Zero baseline context cost; loads only when you type /name or another skill calls it via Skill().
• Skill() — internal companion. Not user-invocable; only called by another skill.

workflow/ — end-to-end orchestrators

Coordinate other skills to ship complete changes.

Skill	What it does	Type
autonomous-workflow	Phase-based orchestrator (0–7): task → plan → worktree → code → test → docs → draft PR → CI gate. Opt-in aw dispatcher routes by tier (Micro/Lite single-pass, Full → planner/executor split). Universal two-tier self-improvement: episodic aw-lessons promotes to gated diagnose at seen_count ≥ 3. See featured section.	auto
fix-bug	10-phase bug pipeline: intake → triage → evidence → repro-lock → analyse → gate → handoff → verify → telemetry. Lane-split: fast for simple, standard for complex. Self-improves via fix-bug-lessons (read Phase 0.5 / write Phase 5·7·8) + promotion to diagnose.	/
batch-linear-tickets	Batch-analyze Linear tickets by dispatching linear-ticket-investigator (plus holistic-analysis for bug tickets) per ticket, gate user approval, then dispatch planners and executors in parallel. Requires Linear MCP. Self-improves via batch-lessons (classification + correlation) and inherits aw-lessons via the fan-out.	/
implement-suggestion	Apply reviewer suggestions across one or more PRs. Reads humans and AI bots (claude[bot], coderabbit, sourcery), validates each via /critical + /confidence, applies in the existing branch.	/
aw-create-plan	Generates .agent/{branch}/plan.md — the source of truth a new session can resume from.	Skill()
aw-create-walkthrough	Generates .agent/{branch}/walkthrough.md — the PR-delivery summary.	Skill()
aw-review-quality-gate	Self-check quality gate for review findings: filters noise, dedupes, ranks severity.	Skill()

quality/ — code, tests, plans, AI apps

Decide whether something is good before you commit to it.

Skill	What it does	Type
code-quality	Authors and reviews code for low cognitive complexity, guard clauses, early returns, single-responsibility.	auto
confidence	Rates confidence that work fully solves the requirement. Modes: plan, code, analysis. Multi-signal gate; deterministic rule checks cap LLM score.	auto
critical	Adversarial pre-mortem: hostile-persona walk through failure modes, blast radius, rollback, hidden coupling, and a mandatory steelman alternative. Never iterates.	auto
tdd	Strict RED-GREEN-REFACTOR cycles. Writes one failing test, implements minimal code, refactors.	auto
test-provenance-guard	Detects tests that pass by construction (re-declare the SUT instead of importing it) via static + mutation checks. Self-heals by extracting inline logic and rewriting the test.	auto
/ai-engineering	Reviews LLM/AI application engineering across 13 concerns: prompts, caching, RAG, agents, resilience, memory, evals, safety, observability.	/
/dx	Reviews CLI tools, shell scripts, and developer tooling against clig.dev, 12 Factor CLI, and Heroku CLI Style Guide.	/
/review-changes	Reviews branch changes or a PR. Dispatches to the reviewer agent.	/

delivery/ — Git, PR, CI

Plumbing for shipping code.

Skill	What it does	Type
/create-pr	Narrative PR description, push, open PR, watch CI, auto-fix simple failures. Flags: --split (multi-PR breakdown), --review (Claude GitHub App + auto-implement loop).	/
/ci-auto-fix	Diagnoses a failed CI check, applies a minimal fix, pushes, iterates until green. Refuses to disable or weaken checks.	/
/resolve-conflicts	Detects merge/rebase conflicts, shows both sides with context, proposes resolutions, asks for ambiguous cases.	/
/changelog	Generates a personal markdown changelog of merged PRs and closed Linear tickets over a configurable window (default 7 days).	/
/github-actions-author	Authors and reviews fast, cheap, maintainable GitHub Actions workflows (2026 best practices). Modes: scaffold, review.	/

testing/ — E2E and fixture tooling

Skill	What it does	Type
/e2e-testing	Spec-first Playwright Test Agents loop (Planner / Generator / Healer, v1.56). Locator ladder, data-testid source diffs, 3-attempt heal cap.	/
/e2e-testing-mobile	Mobile counterpart on Maestro YAML flows for Expo / React Native. testID-first locator ladder; runs on Maestro Cloud via EAS Workflow.	/
/e2e-pr-stabilizer	Local-first stabilizer for Playwright E2E on one PR. Pulls Dash0 MCP spans (git.pull_request_link) as historical baseline, then iterates locally with --trace=on and the same OTel exporter. Validation is empirical, not predictive: every new locator must resolve against source (static grep) or the live app (locator.count() ≥ 1) before commit, and the fixed test must pass 3 consecutive local runs before the single push. CI watch ratifies. Refuses .skip / .fixme / waitForTimeout. Modes: stabilize (default) and optimize (report-only, ranks slow-action wins by measured ms saved).	/
/optimize-mock-data	Optimizes JSON/JSONL fixture directories via shared-schema inference, drift detection, safe shrink/normalize.	/

design/ — UI, visual, interaction

Skill	What it does	Type
animations	CSS-first web animation. Three modes: Brainstorm, Perceived-Performance, technical workflow (CSS → WAAPI → Motion → R3F).	auto
charting	Selects chart type + visualization library for web (React/Next.js) and mobile (Expo/RN). Maps intent → chart → library based on platform and dataset size.	auto
storybook	Scaffolds three artefacts per component: visual regression story, Playground, interaction test. Opt-in OS-keychain auth profiles.	auto
ux	Reviews UI for usability, WCAG 2.2 accessibility, platform compliance (Apple HIG, Material Design 3), and dark-pattern detection. Hard rule: never recommends a dark pattern.	auto
visual-design	Generative, brand-aware visual design. Style-direction taxonomy (minimal, swiss, brutalist, glass, …), color systems, typography, signature details. Defers WCAG math to /ux.	auto

analysis/ — investigate data, diagnose issues

Skill	What it does	Type
holistic-analysis	Forces a full entry-to-exit execution-path trace when incremental fixes aren't working.	auto
rum-tracking	Guides product analytics and RUM event tracking for web (React/Next.js) and mobile (React Native/Expo). Decides what to track, what's noise, what's PII; covers OTel semantic conventions, tracking plans, GDPR/CCPA compliance, and clean implement / audit / remove workflows.	auto
video-analyser	Analyses a screen recording for bugs. Resolves input from a Linear ticket URL, local path, or direct URL. Optional Tesseract OCR and Whisper transcription.	auto
/profile-optimizer	Analyses React DevTools Profiler exports or Chrome Performance traces. Maps hotspots to source. Iterates via confidence(analysis) until ≥ 90%.	/
/playwright-trace-analyzer	Analyses Playwright trace.zip (or downloads from a GitHub Actions run URL). Names the race behind a flake, emits a ranked fix plan.	/
/screen-recorder	Records short cropped videos of UI sections via Playwright + ffmpeg. Validates multi-frame interactions a screenshot can't prove.	/

authoring/ — skills about Claude Code itself

Meta — scaffolding new skills, maintaining docs, persisting memory.

Skill	What it does	Type
documentation	Authors and audits CLAUDE.md, AGENTS.md, README.md, and Diátaxis docs/ trees. Modes: init, update, readme, audit.	auto
/create-skill	Scaffold, review, upgrade, or diagnose agent skills. diagnose <target> is the retrospective self-improvement entry point.	/
/optimize-claude-md	Audits CLAUDE.md for context bloat. Modes: audit, trim, extract. Flags rarely-used agent-invokable skills that should become slash-only.	/
/persistent-memory	Persists context across conversations as plain markdown, scoped per topic. Operations: write, read, consolidate, forget. Three storage tiers. Also backs autonomous-workflow's aw-lessons self-improvement loop.	/

Agents at a glance

Agents are specialized sub-processes with their own model and tool configuration. Dispatched by other skills, not invoked directly.

Agent	What it does
reviewer	Own-work code reviewer (own branch or own PR). Three sub-modes: Fix (auto-fix simple + plan complex), Report (--report, propose only), Self-Review (own PR, auto-fix + inline terminal report). Never writes to GitHub — redirects to pr-reviewer on a cross-author PR. Orthogonal --with <skill> loads up to 3 additional lenses.
pr-reviewer	Cross-review reviewer for someone else's PR. Authors short, grounded, confidence-gated inline comments (≤ 240 chars, ≤ 2 sentences, Skill("confidence") ≥ 80) and (with --publish or an explicit authorization phrase) posts them as a PENDING review invisible to the author until you submit from the GitHub UI. Refuses on your own PR (points to reviewer).
linear-ticket-investigator	Reads a Linear ticket, returns an Evidence Record matching /fix-bug Phase 2. Customizable via a per-project domain navigator.
bug-fix-verifier	Independent fresh-context verifier for /fix-bug PRs. Runs FAIL_TO_PASS, PASS_TO_PASS, diff sanity, repro integrity. Only agent allowed to undraft.
feature-pr-verifier	Feature-PR counterpart to bug-fix-verifier. Verifies acceptance criteria, pass-to-pass, walkthrough integrity for autonomous-workflow Full Mode.

Featured: autonomous workflow

autonomous-workflow orchestrates a complete feature cycle — from a one-line task to a tested draft PR — using isolated Git worktrees.

Three agents, one workflow

The skill installs an opt-in dispatcher plus the two specialist agents it routes to for complex work, connected by plan.md:

Agent	Role	Exit gate
aw	Opt-in dispatcher: reads lessons, detects tier (Micro/Lite/Full), routes single-pass vs the split, owns the self-improvement loop for every tier	Task routed + exit lesson written
aw-planner	Full tier, 0–2 (validate, plan, worktree + plan.md)	confidence(plan) ≥ 90%
aw-executor	Full tier, 3–7 (implement, test, docs, PR, CI)	CI green, walkthrough delivered

All share the aw- prefix ("autonomous-workflow"): deliberate namespace so they group together in ~/.claude/agents/ and disambiguate from agents installed by other skills. aw is adaptive — it only invokes the planner→executor split for Full tasks; Micro/Lite run single-pass.

Phases

Phase	Name	Companions (optional unless marked)
0	Validation	—
1	Planning	holistic-analysis, code-quality, confidence(plan) (mandatory)
2	Worktree + plan.md	aw-create-plan (Full Mode)
3	Implementation	tdd, ux, code-quality
4	Testing	confidence(analysis), holistic-analysis (auto-replan once at cap)
5	Documentation	documentation update
6	PR creation	review-changes, aw-create-walkthrough, create-pr
7	CI gate	ci-auto-fix

The mode-aware stuck-loop cap at Phase 4 (3 Lite / 5 Full) is the biggest cost-saver: it prevents agents burning tokens on hallucinated fixes when their root-cause analysis is wrong.

Setup

The clone + symlink install already links the three aw- agents and the routing rule — sync-symlinks.sh runs the dispatcher installer for you. If you used npx skills add instead, run the dispatcher installer manually:

bash ~/.claude/skills/autonomous-workflow/install.sh --global

Companions (tdd, ux, code-quality, documentation, ci-auto-fix, …) skip silently if absent — see Customizing to opt out individually. Drop --global for a per-project install. Requires gh; gw is optional (native git worktree fallback).

Further reading

• skills/workflow/autonomous-workflow/README.md — install, customize, migrate from v2
• skills/workflow/autonomous-workflow/CLAUDE.md — design intent
• skills/workflow/autonomous-workflow/rules/companion-skills.md — companion registry
• skills/workflow/autonomous-workflow/references/anthropic-architecture-research.md — rationale for the two-agent split

Usage examples

Agent-invokable skills activate from natural language — just describe what you need.

Implement this feature autonomously / end-to-end / in a worktree
Check the accessibility of this component
I've tried fixing this bug three times — step back and analyze holistically
Add this feature using TDD
Rate your confidence in this implementation
Analyse this screen recording for bugs

Slash commands are typed explicitly.

/batch-linear-tickets SUP-123 SUP-456
/fix-bug https://app.dash0.com/.../trace?spanId=...
/dx review my CLI tool
/profile-optimizer ./trace.json
/documentation init
/documentation update
/documentation readme
/documentation audit
/resolve-conflicts
/review-changes --comments 42
/implement-suggestion <pr-url> [<pr-url> ...]
/create-pr
/ci-auto-fix <run-id|pr-url>

Install

Two ways in:

Path	Stays current?	Customizable?	Best for
Clone + symlink (recommended)	Yes — git pull updates everything live	Yes — edit any skill in place	Living with these skills day to day
npx skills add	No — installs a frozen copy you re-fetch to update	No — edits are overwritten on re-fetch	A quick, no-clone trial — one skill or all

Recommended: clone + symlink

git clone https://github.com/mthines/agent-skills.git
cd agent-skills
bash scripts/sync-symlinks.sh

The script builds a two-tier symlink chain, so a single clone serves every Agent Skills–compatible tool:

~/.claude/skills/<name>     →  ~/.agents/skills/<name>     →  <clone>/skills/<category>/<name>
~/.claude/agents/<name>.md  →  ~/.agents/agents/<name>.md  →  <clone>/agents/<name>.md

Because skills are symlinked, your edits and every git pull land on the next agent turn — no reinstall. The middle layer (~/.agents/skills/) is the cross-tool discovery directory other tools read. Run it with bash, not sh; pass --dry-run to preview.

Any skill that ships its own install.sh (currently only autonomous-workflow, which links three aw- agents and a routing rule) auto-runs at the end of the sync — no separate step.

Upgrading

cd agent-skills && git pull
bash scripts/sync-symlinks.sh   # only to wire up newly added skills/agents

git pull updates every symlinked skill in place. Re-run the sync script only to pick up skills or agents that are new since your last pull — it's a no-op for everything already linked.

Coming from npx skills add? That copy never tracks upstream — which is why upgrading felt hard. Delete the copied entries from ~/.claude/skills/ (and ~/.agents/skills/), then switch to clone + symlink. After that, git pull is the whole upgrade.

Customize and still track upstream

To bend a skill to your own preferences and keep pulling new changes, fork and track this repo as upstream:

# Clone YOUR fork, then add this repo as upstream:
git clone https://github.com/<you>/agent-skills.git
cd agent-skills
git remote add upstream https://github.com/mthines/agent-skills.git
bash scripts/sync-symlinks.sh

# Edit any skill, commit to your fork, and pull new work anytime:
git pull upstream main

Customizations live on your fork; git pull upstream main merges in upstream changes. Keep edits scoped to the skills you actually change so merges stay clean.

Quick try: npx skills add

A no-clone way to grab one skill or the whole collection. This installs a frozen copy — re-run to pick up changes; it does not track upstream.

Keep it tidy. Always pass --agent <your-tool> (e.g. --agent claude-code). Without it, npx skills symlinks every skill into ~24 different AI-tool directories at once.

# One skill, Claude Code:
npx skills add https://github.com/mthines/agent-skills --skill confidence --agent claude-code --yes

# All skills, Claude Code:
npx skills add https://github.com/mthines/agent-skills --all --agent claude-code

# Universal — any Agent Skills tool:
npx skills add https://github.com/mthines/agent-skills --all

Other tools (Claude Code marketplace, Gemini, manual clone)

# Claude Code plugin marketplace:
/plugin marketplace add mthines/agent-skills
/plugin install mthines-agent-skills@mthines

# Gemini CLI:
gemini extensions install https://github.com/mthines/agent-skills

# Cursor / Copilot / Codex / manual — most tools auto-discover ~/.agents/skills/:
git clone https://github.com/mthines/agent-skills.git ~/.agents/skills/mthines-agent-skills

VS Code extension

The vscode-agent-tasks package visualizes plan.md, task.md, and walkthrough.md in the VS Code sidebar — phase progress, decisions, blockers, and completed checkboxes update live as the agent works.

Install from the Marketplace by searching for Agent Tasks or:

mthines.agent-tasks

Default scan paths are .agent/ and .gw/. Configure via agentTasks.directories. See packages/vscode-agent-tasks/README.md for full docs.

For live session status in the panel, add the optional agent-tasks-hooks Claude Code plugin — it emits privacy-safe NDJSON lifecycle events the extension reads. It's only useful with the extension installed:

/plugin marketplace add mthines/agent-skills
/plugin install agent-tasks-hooks@agent-skills-plugins

Linear ticket investigator (per-project plug-in)

The linear-ticket-investigator agent returns an Evidence Record from a Linear ticket. Investigation accuracy depends on grounding the agent in your project's structure.

The agent looks for context in this order:

1. Top-level CLAUDE.md / AGENTS.md.
2. Component-specific CLAUDE.md / AGENTS.md in directories the ticket points at.
3. A domain-navigator skill, auto-discovered by name.
4. Top-level README.md (fallback).

Steps 1, 2, and 4 work out of the box. Step 3 is the high-leverage customization for monorepos.

Naming convention

The investigator scans its available-skills list at runtime for any skill whose name is:

• exactly domain-navigator, or
• ending in -domain-navigator — e.g. dash0-domain-navigator, acme-domain-navigator.

Any match is invoked automatically. No agent code changes, no registration.

Starter template

Create .claude/skills/<project>-domain-navigator/SKILL.md:

---
name: <project>-domain-navigator
description: >
  Maps Linear labels and ticket terminology to component directories in <project>.
  Surfaces cross-component dependencies. Use during investigation or planning.
user-invocable: true
---

# <Project> Domain Navigator

## Label → directory map

| Label | Component paths                       |
| ----- | ------------------------------------- |
| ui    | components/ui/, packages/web/         |
| api   | components/api/, packages/server/api/ |

## Cross-component dependencies

- `ui` calls `api` via `packages/web/src/client/`
- `api` reads from `db-migrator` schemas in `packages/db/`

## Where the docs live

- Architecture overview: `docs/architecture.md`
- API contract: `packages/server/api/openapi.yaml`

That is the entire integration.

Repository structure

skills/                   39 skills, each with SKILL.md (some with rules/, references/, templates/, scripts/)
agents/                   5 agents (reviewer, pr-reviewer, linear-ticket-investigator, bug-fix-verifier, feature-pr-verifier)
plugins/                  1 Claude Code plugin (agent-tasks-hooks)
packages/                 VS Code extension (vscode-agent-tasks)
.claude-plugin/           marketplace.json — plugin distribution manifest
scripts/                  Local symlink sync (scripts/sync-symlinks.sh)

Each skill has a SKILL.md manifest with YAML frontmatter (name, description, metadata) and a Markdown body with instructions. Skills with rules/ subdirectories contain focused guidance documents that load on demand. Agents live in agents/ because they require their own model and tool configuration.

Local development

If you installed via clone + symlink, you're already set up: every skill is live-linked, so edits to skills/<category>/<name>/SKILL.md take effect on the next agent turn.

Add a new skill

1. Create skills/<category>/<name>/SKILL.md in this repo.
2. Run bash scripts/sync-symlinks.sh to wire the symlink chain for every new or missing skill/agent (--dry-run to preview).
3. Add an entry to the inventory in CLAUDE.md and this README.

For agents, write agents/<name>.md and rerun the sync script.

If your skill needs extra wiring beyond the standard symlink chain (e.g. linking template files as agents, like autonomous-workflow), ship a skills/<category>/<name>/install.sh. The sync script discovers it automatically and invokes it with --development --quiet after the main pass. Contract: accept both flags, be idempotent, write errors to stderr.

Edit an existing skill

Edit skills/<category>/<name>/SKILL.md directly in this repo — never through the ~/.claude/skills/ symlink, or it gets ambiguous which checkout you touched when multiple worktrees exist.

Verify the chain

readlink ~/.claude/skills/<name>      # → ~/.agents/skills/<name>
readlink ~/.agents/skills/<name>      # → <repo>/skills/<category>/<name>

Both must resolve. If either is missing, the agent harness won't see the skill.

Contributing

PRs welcome. Read CLAUDE.md for the prose conventions and skills/authoring/create-skill/SKILL.md for the skill-authoring rubric.

License

MIT