Agent Skills

Audience

Agentic frameworks (AI coding agents, copilots, autonomous developer tools) consume these skills and agents operationally, so every line must be actionable without human interpretation:

• Be prescriptive: tell the agent what to do, not what a concept means.
• Make decisions enumerable: numbered steps, lookup tables, or explicit criteria.
• Give every actionable rule a code example showing the correct and the incorrect pattern.
• State concrete, testable criteria, never subjective ones.
• Keep each file self-contained.

Where knowledge goes (mandatory on every change)

This file loads into every session, so it holds only what an agent needs on every task. Classify what you learned and write it only where the table says:

• Keep a sentence only if deleting it would change how an agent acts; narrative ("this used to…"), release-version tags, and incident retellings fail that test.
• docs/inventory.md and docs/evals.md are frozen archives: read them, never append to them.
• An inventory hook names the capability, never its history: - `review-loop` (`Skill()`) — bounded PR convergence loop; `--merge` squash-merges on a clean convergence, not … **`--merge` (vN.N):** … a real run on #214 showed ….
• L1 G86 enforces the mechanical half: this file stays under 40,000 chars, inventory hooks stay ≤ 300 chars, no version tags, and the two archives do not grow.

Repository structure

Skills live in skills/<category>/<name>/SKILL.md (7 categories); agents live in agents/ because they need their own model and tool configuration. A skill's SKILL.md is its operational authority; its rules live in rules/, their rationale in references/. Type markers name the primary entry point: auto = the description auto-triggers on natural language; / = slash command, no auto-trigger; Skill() = called by another skill or workflow. All three stay model-invocable via Skill() when disable-model-invocation: false.

workflow/ — end-to-end orchestrators

• autonomous-workflow (/) — phase machinery behind aw; plan.md is a six-heading brief gated on run-checks.mjs printing CHECKS M/M PASS, ending in a paste-ready /goal. aw (auto) is the sole entry and owns tiers. Design: CLAUDE.md
• aw-create-plan (Skill()) — writes the plan.md brief (Task, Requirements, Guardrails, Definition of Done, Turn Cap, File Changes) + sealed checks.yaml. aw-create-walkthrough (Skill()) — writes walkthrough.md, led by a one-page review summary
• fix-bug (/) — single-bug pipeline, phases 0–8
• implement-suggestion (/) — apply reviewer suggestions across PRs; --watch loops one PR, --resolve-all closes non-fix threads. Never fixes CI

quality/ — code, tests, plans, AI apps

• ai-engineering (/) — LLM/AI app review across 13 concerns
• confidence (auto) — multi-signal confidence gate for plan / code / analysis; deterministic rule caps the LLM score at 89%
• critical (auto) — adversarial pre-mortem with mandatory steelman alternative. Never iterates; deep runs 3–5 parallel persona lenses (found via ideate) and merges them
• measurable (auto) — every delivery ships telemetry that proves impact and surfaces regressions; modes guide / implement / audit / setup
• optimize-approach (/) — is this the best approach for the intent (codebase-fit, simplicity, performance, robustness); at most two material proposals, silent when sound. Report only
• polish (/) — re-runnable pre-PR branch quality gate: review, then simplify the diff and prune restating or ticket comments, each change behind a test check
• review-loop (Skill()) — bounded convergence loop, cap 5: pr-reviewer → implement-suggestion --resolve-all → polish simplify on a PR; with no PR, local mode over .agent/{branch}/findings.jsonl, zero GitHub calls; --ui adds a ui-verify lane. Run at the top level
• pr-review (/) — one read-only pr-reviewer dispatch at one PR; nested REVIEW.md files, read from the base, brief every finder automatically; .agents/review/lenses/*.md team lenses load by path; /pr-review remember <fact> writes a maintainer relevance rule
• impact-map (auto) — impact-first PR view: verdict with expandable What/Risk/Ask rows, one badged diagram, ≤ 3 decisions with linked lines, a settled list; several refs or --stack map each PR and name shared risks; --comment / --body post it with PNGs
• tdd (auto) — strict RED-GREEN-REFACTOR; provenance mode checks a test exercises the production code (static + mutation)
• verify-behavior (Skill()) — cheapest-first three-tier verification ladder; emits an evidence receipt, never a score
• jev-assert (Skill() + /) — semantic UI assertion via TypeSafe Jev; backs the THEN semantic: spec form

delivery/ — Git, PR, CI

• attach-media (Skill() + /) — uploads screenshots and recordings to a PR or issue via gh --attach, with a curl fallback; owns the <!-- attach-media:v1 --> body region. Never writes placeholders
• ci-auto-fix (/) — evidence-gated CI diagnosis and fix; never weakens checks
• create-pr (/) — narrative PR description; pre-push local review-loop, draft PR, post-draft review-loop, CI watch
• github-actions-author (/) — author / review GHA workflows
• resolve-conflicts (/) — analyze and resolve merge / rebase conflicts

testing/ — E2E and fixture tooling

• e2e-testing (/) — spec-first Playwright Test Agents loop
• e2e-testing-mobile (/) — Maestro YAML flows for Expo / React Native
• aw-verify (/) — proves a feature works on local or preview: probes specs, concurrency, and guardrail faults, reads telemetry once via telemetry-verify, fixes locally, posts proof and media to the PR's one verify comment. setup writes .agents/aw/
• ui-verify (Skill() + /) — browser witness: Markdown intent spec in the PR body (<!-- ui-verify:v2 -->); checks every outcome with evidence, then tries to break it and records it; profiles a motion diff's frames and reduced motion; posts its ui region of the PR's verify comment
• telemetry-verify (Skill()) — telemetry witness: reads one traffic window's web events, traces, and logs; follows each criterion from web event to API to database; grades the brief's telemetry: criteria; run alone, posts its telemetry region

design/ — UI, visual, interaction

• animations (auto) — CSS-first web animations and perceived performance; is-motion-diff.mjs gates its lens.md into pr-reviewer and a motion profile into ui-verify
• animations-native (auto) — React Native / Expo animations (Reanimated, gesture-handler)
• behavioral-design (auto) — behavior-change diagnosis (COM-B, B=MAP), ethical interventions (EAST, defaults, System 1 / System 2), and team-adoption workshops. Never recommends a dark pattern or sludge
• charting (auto) — chart type + library for web and mobile
• storybook (auto) — visual regression, Playground, and interaction-test stories
• ux (auto) — UX, a11y, microcopy, dark-pattern review. Never recommends a dark pattern
• visual-design (auto) — brand-aware visual direction

analysis/ — investigate data, diagnose issues

• ideate (auto) — research-grounded brainstorming; divergence runs lessons-blind
• interview (auto) — pre-plan scope-alignment interview; emits .agent/{branch}/brief.md
• playwright-trace-analyzer (/) — analyze trace.zip; names the race behind a flake
• profile-optimizer (/) — React DevTools / Chrome Performance trace analysis
• rum-tracking (auto) — product analytics and RUM event tracking
• screencast (auto + Skill()) — browser video engine: overlay (cursor, click ring, step captions), finish.mjs → mp4 + per-step timings.json + contact sheet with frozen waits cut, capture.mjs for a Chrome tab over DevTools; shared by ui-verify and both aw-tester runners
• video-analyser (auto) — analyze screen recordings for bugs
• youtube-transcript (auto) — stdlib-only YouTube transcript fetch that works from cloud IPs where youtube-transcript-api and yt-dlp are bot-blocked

authoring/ — skills about Claude Code itself

• create-skill (/) — scaffold (runs the job once without a skill, then writes only the corrections), diagnose, and prune (unused or zero-lift vs. a dummy) skills
• docs (auto) — author / audit CLAUDE.md, AGENTS.md, README.md, Diátaxis docs/ trees
• optimize-claude-md (/) — audit CLAUDE.md for context bloat
• persistent-memory (/) — cross-conversation markdown memory store. Self-improvement loops run on LoreKit instead; bucket taxonomy: memory-buckets.md
• handoff (/) — copy-pasteable session handoff for a fresh agent

Agents

aw is a skill, not an agent — aw/SKILL.md, invoked /aw. The agents it hands off to are generated from templates in skills/workflow/autonomous-workflow/templates/, not stored in agents/:

• aw-executor — Full tier, executes the brief aw writes, phases 3–7. Source: aw-executor.agent.md
• aw-tester — Phase 4 spec-driven UI verification. Source: aw-tester.agent.md

The agents below live as agents/*.md files and are dispatched by skills:

• pr-reviewer — PR reviewer for self and cross relations; read-only; one sticky report comment plus append-only inline findings
• branch-reviewer — PR-less reviewer for review-loop local mode; writes .agent/{branch}/findings.jsonl, zero GitHub calls
• feature-pr-verifier — independent verifier for /autonomous-workflow Full Mode PRs

Commands and gotchas

Read docs/development.md when adding, wiring, or debugging a skill, agent, plugin, or package.

bash scripts/sync-symlinks.sh            # wire every new skill/agent into ~/.claude via ~/.agents
bash scripts/sync-symlinks.sh --dry-run  # preview
node skills/authoring/create-skill/scripts/validate-skill.mjs skills/<category>/<name>  # frontmatter + body lint
pnpm install                             # from repo root, for packages/

• Run sync-symlinks.sh with bash, never sh (it uses bash arrays and process substitution).
• Edit skills in this checkout, never through the ~/.claude or ~/.agents symlinks; the symlinked path hides which worktree the edit lands in.
• A new skill needs SKILL.md, a sync-symlinks.sh run, an inventory hook above, and a README.md entry.
• A skill-local install.sh must accept --development --quiet, be idempotent, and write errors to stderr.
• Name a file an installer symlinks verbatim <agent-name>.agent.md or <name>.rule.md; reserve *.template.md for boilerplate a skill fills in at runtime.
• Plugins live in plugins/<name>/ (no build step), listed in .claude-plugin/marketplace.json; validate with claude plugin validate plugins/<name>.
• Packages live in packages/ (Nx); never add one without updating tsconfig.json references and the nx.json release config. VS Code extension commands and internals: packages/vscode-agent-tasks/CLAUDE.md.

Evals

Harness docs: scripts/eval/README.md.

• plugin-eval (pnpm plugin-eval --tag ablation): evals/ runs each key skill with and without the plugin loaded; a skill whose Δ stays ≤ 0 is a slimming candidate. Opt-in, never in CI; L1 G110 keeps every case loadable.
• L1 (node scripts/eval/l1.mjs): deterministic integrity checks, free, CI-gated on every PR. A new check must pass the L1 admission rule; prose, wording, and sync checks are never admitted.
• L2 (ANTHROPIC_API_KEY=… node scripts/eval/l2.mjs [--suite a,b]): one suite per labelled decision; goldens in scripts/eval/golden/, suites in scripts/eval/suites.mjs. Opt-in in CI via the run-evals PR label (aggregator check evals · L2 (behavioral) / l2).
• L2-detection (ANTHROPIC_API_KEY=… node scripts/eval/l2-detection.mjs, --self-test offline): finder → verifier over golden/bug-detection.jsonl, hard-gated on recall ≥ 0.7 and fp ≤ 0.2. Never lower a gate or loosen the parse to pass.

Keeping the evals honest (mandatory on every change)

A change that alters a decision the evals measure updates the evals in the same commit. These triggers are exhaustive:

• Suites do not run unasked in CI: after any first-row change, label the PR run-evals or run the suites locally, and put the accuracy in the PR description.
• node scripts/eval/select-suites.mjs on your changed files lists the suites the first row covers.
• Done means the diff touches the eval surfaces above, or the PR description says in one line why none applied.

Prose rules

• One sentence per line (semantic line breaks).
• Use inline Markdown links.
• Fence code with a language identifier.
• End sentences with full stops.
• Use the Oxford comma.