agents-skills: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

A public, shareable collection of AI toolchains — Skills and Agents — meant to be consumed by others across multiple AI coding tools (Claude Code, GitHub Copilot, Cursor). It is a content/config repo: there is no application code, no build step, and no test runner. "Correctness" here means each artifact is valid for its target tool and works when dropped into a consumer's environment.

Because it is public and reusable, every artifact must be clean of personal and prior-project data. No employer names, internal URLs, ticket IDs, secrets, file paths from private repos, or learnings that only make sense inside one codebase. Keep learnings isolated — phrased generically so they apply anywhere.

Primary goal: extreme token savings at the highest practical accuracy. Every authored skill operates in caveman mode for terse working output, and model spend is tiered — the cheapest capable model per task, with mechanical work offloaded to a cheap-tier subagent and premium reserved for operator-gated hard reasoning. See MODEL-DEFAULTS.md.

Repository layout

Skills and Agents are the two primary artifact types. The canonical homes are the directories Claude Code auto-discovers:

• .claude/skills/<skill-name>/SKILL.md — one directory per skill; SKILL.md holds YAML frontmatter (name, description) + the skill body. Supporting files (references/, scripts) live alongside it.
• .claude/agents/<agent-name>.md — one file per agent; frontmatter (name, description, tools, optional model) + system prompt. Ships 18 tiered worker agents (scout on the cheap tier; builder, reviewer, implementer, pr-rescuer, diagnostician, verifier, spelunker, design-mapper on workhorse — these the commands dispatch — plus the pr-dispatcher, pr-comments, pr-checks, pr-cleanup single-lane PR watchers, the deploy-watcher deploy-health lane, and the ci-speed-hunter, ci-flake-hunter continuous CI lanes, the token-bleed-hunter token-efficiency lane and the branch-ff fast-forward lane, all run via /loop). Canonical agents live here; make sync-agents generates the Cursor (.cursor/agents/, model/readonly schema), Copilot (.github/agents/*.agent.md), Kiro (.kiro/agents/, tools category allowlist) and OpenCode (.opencode/agents/, mode/permission) copies — never hand-edit those. Keep agents thin and point at the relevant skill for the protocol.
• .claude-plugin/marketplace.json + plugins/agents-skills/ (Claude Code) and .cursor-plugin/marketplace.json + plugins/agents-skills-cursor/ (Cursor) — this repo doubles as its own plugin marketplace for both ecosystems. Same skills in each (the Agent Skills format is identical); agents and commands come from that tool's generated mirror, since their frontmatter differs. The plugin payload is generated from .claude/{skills,agents,commands} by make build-plugin (real copies, not symlinks — Claude Code installs the plugin dir standalone, so a link escaping it would dangle); make check-plugin fails on drift. Never hand-edit plugins/. Releases are cut by .github/workflows/release-plugin.yml: CalVer YYYY.M.D.N (patch counter so same-day releases never collide), tag v<version>, assets = a full-plugin zip + one zip per skill (the latter for Claude Desktop). The workflow stamps versions — never bump them by hand.
• .claude/settings.json — repo-level Claude Code config. Currently pins model: opus and includeCoAuthoredBy: false (commits authored without the Claude co-author trailer).