agent-skills

Rigorous engineering process for AI coding agents, packaged as portable Agent Skills: implement a spec end-to-end to a verified PR, review code with independent judgment — your own branch, or anyone's PR — work through review feedback like a professional author, and keep documentation (agent-facing and human-facing) converged with the code it describes.

• Harness-agnostic — standard SKILL.md directories. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and a growing list of clients load them natively; anywhere else (Windsurf, Goose, a human with a terminal), a one-line pointer to the skill file works.
• Codebase-agnostic — no assumptions about your repo, language, or toolchain. Build/test/lint commands are discovered from the repo or passed as inputs, never hardcoded.
• Research-grounded — durable ledgers, fresh-context review, evidence-first reporting: the design decisions trace to the agent-engineering literature (rationale).

The flagship: implement-spec

Most agents can write plausible code from a spec. What they don't do reliably is everything around that — hold the plan across a long horizon, test what they wrote, catch where the implementation quietly diverges from the spec, and prove the result rather than assert it. implement-spec packages that discipline: hand it an agent-ready spec, and it runs the lifecycle autonomously, surfacing only at the end.

spec ─▶ branch ─▶ plan + test matrix ─▶ implement (tests alongside)
     ─▶ two-pass self-review ─▶ gap analysis vs the spec ─▶ close gaps
     ─▶ live verification ─▶ PR + acceptance-criteria evidence report

• Evidence over claims — "done" means every acceptance criterion in the final report maps to a verifiable artifact (a test, a command's output, a live check) — not that the model says so.
• Survives long horizons — a durable run ledger on disk makes the run resumable across crashes and context compaction.
• Proportional rigor — every heavyweight phase (ledger, self-review, gap analysis, tests, live verification) is individually opt-out, so a one-line fix doesn't pay a ten-phase tax.

The full design rationale, with the literature behind each phase, is in skills/implement-spec/README.md.

The skills around it

Ten more skills stand alongside it — five cover the multi-session build lifecycle, three review and answer, two document:

Skill	Purpose
synthesize-spec	Turn a brief into a ratified, decomposable spec: a research ledger executed in fresh contexts, then synthesis, adversarial review, and operator ratification — the upstream half
decompose-spec	Split one large spec into the fewest self-contained tickets that each fit a single fresh context, and seed the committed build memory — the planning half of a multi-session build
orchestrate-build	Drive that chain to completion: run each ticket through implement-spec in a fresh context, report progress, pause for intervention, finish with the standard tail — the execution half
build-memory	Owns the committed build-memory layout (docs/build/, docs/tickets/, docs/adr/), templates, validator, and legacy-scratch migration — the shared layer the build skills cite
reconcile-build	The closeout the tail tickets invoke: one complete backlog + operational readiness, spec reconciliation, and a read-only integration plan
self-review	Two-pass review of your own branch, pre-PR: mechanical verification, then independence-preserving design critique
review-pr	Review someone else's PR: CI/verification grounding, focused design + security passes, calibrated severities, high-precision inline comments

The build lifecycle, end to end

A large build runs as a chain of stages, each owned by a skill and leaving a committed artifact the next stage reads:

Stage	What happens	Owning skill(s)
S0 Brief	the founding prompt is captured (docs/brief.md)	operator / synthesize-spec
S1–S3 Research → spec	research ledger rows executed in fresh contexts; the spec synthesized, reviewed, and ratified	synthesize-spec
S4 Decomposition	the ratified spec split into a dependency-ordered ticket chain; build memory seeded	decompose-spec + build-memory
S5 Build	each ticket run end-to-end in a fresh context; the worker closes its own ledger	orchestrate-build → implement-spec
S6 Capstone	whole-build gap analysis → composed verification → closure → operator sign-off, as tail tickets	CAP.* / GATE-ACCEPT tickets
S7 Reconciliation	one backlog + readiness, spec reconciliation, integration plan	reconcile-build (via REC.*)
S8 Docs	human-facing and agent-facing docs converged with the code	refresh-repo-docs + (via )

Every stage's state is committed under docs/ (the layout is skills/build-memory/layout.md); only regenerable logs are gitignored.

The multi-session build

When a spec is too large for one focused run, decompose-spec and orchestrate-build turn it into a resumable chain of PRs — implement-spec is still the per-ticket worker, run once per ticket in a fresh context:

• decompose-spec is the planner, and the quality ceiling of the whole build: it partitions the spec to a precise objective — the fewest tickets such that each fits one fresh context with rigor headroom and no cut severs a shared implicit decision — then reviews its own split in a fresh context and seeds the build ledger. The two bounds (context rot above, fragmented decisions below) trace to the rationale.
• orchestrate-build is the driver. Its key move: sequencing is deterministic code — a portable loop (drive-build.sh that discovers claude -p / goose run / codex exec / gemini -p) that holds no state and dispatches each ticket to a fresh context — so nothing accumulates context across the build and there is no long-lived agent context to rot. State lives in the ledger; the human pauses and intervenes at ticket boundaries by editing it. At every boundary the PR checks are read (ci-boundary.sh), and the loop refuses to dispatch past a red, pending or unreadable PR; the history check proves protected records only gained lines, and an operator digest (digest.sh) reports red PRs, outside merges, owed human work and spend at every pause. Degrades to a subagent-per-ticket or a manual fresh-session floor (drive-build.sh --print-prompt) where a harness offers less; the rationale covers why it stays harness-agnostic.

The review suite

Three seats at the same table, sharing one epistemology — every flag must be demonstrable, and precision beats recall (false positives are how reviewers lose the room):

• self-review is the author pre-PR: Pass 1 runs auto-discovered build/test/lint (via verify.sh, which infers the toolchain when the repo doesn't declare one) plus binary checklists; Pass 2 is design critique under independence rules — fresh context where the harness supports subagents, evidence-from-disk discipline where it doesn't. Also implement-spec's review phase.
• review-pr is the reviewer's seat: grounded in CI and (optionally) local verification, then separate focused passes for correctness, design, security, and scope; findings gated by demonstrability → confidence → novelty → materiality, labeled blocking/important/nit/question, capped to prevent alert fatigue, posted with suggestion blocks. It informs — approval stays human.
• address-pr-comments is the author answering: every unresolved thread gets a fix, a commit link, a reasoned push-back, an answer, or a scoped follow-up — never silence, never sycophancy, never a mid-review force-push.

The docs pair

Same convergence philosophy, two corpora with different consumers and quality bars — each with a deterministic, CI-gateable drift detector in front of the LLM work:

• agent-docs owns the agent-facing knowledge layer (AGENTS.md hierarchy) the other skills run on. Two modes — bootstrap (reconnaissance → gotcha mining → generation) and refresh (drift triage → surgical fixes) — auto-selected by a detector that classifies broken references as went stale vs authoring error using git history. Owns the shared Doc Authoring Guidelines.
• refresh-repo-docs owns what humans read: README, docs/, CHANGELOG, guides, examples. Its detector flags broken references and docs older than the code they cite; the audit is scoped by evidence (flagged docs, not "read the whole repo"), findings are classed stale/cruft/gap/mode-drift with Diátaxis as the per-doc quality lens, and no claim is written unverified.

Install

As a Claude Code plugin:

/plugin marketplace add SteveVitali/agent-skills
/plugin install agent-skills@agent-skills

Or by symlink, for any client that discovers skills on disk (~/.claude/skills/, a project's .agents/skills/, etc.):

git clone https://github.com/SteveVitali/agent-skills.git ~/agent-skills
ln -s ~/agent-skills/skills/* ~/.claude/skills/

Clients without native skill support (e.g. Windsurf): a one-line workflow or rule pointing at the skill file is enough — "Read and follow <path>/skills/implement-spec/SKILL.md".

Each skill declares its inputs in SKILL.md frontmatter; state them in natural language ("implement docs/spec.md, skip the ledger, base off main"). System requirements: git, bash 3.2+, and standard Unix tools; the PR skills (review-pr, address-pr-comments) additionally need an authenticated GitHub CLI (gh).

Repo layout

.claude-plugin/                # plugin + marketplace manifests (Claude Code)
CHANGELOG.md                   # notable changes, by plugin version
tests/lint-skills.sh           # skill-text lint: retired phrases, required rules, rule ids resolve
skills/<skill-name>/
├── SKILL.md             # entry point (Agent Skills format: frontmatter + steps)
├── README.md            # design rationale (where it exists)
├── layout.md            # shared reference contract (build-memory owns the build layout)
├── modes/               # mode-specific step files, loaded on demand (where applicable)
├── scripts/             # supporting shell helpers (bash 3.2+ compatible)
├── templates/           # artifact templates a skill instantiates (e.g. build-memory)
├── tests/               # fixture repos / stubs + run-tests.sh self-test (build-memory, orchestrate-build, agent-docs)
├── guidelines.md        # shared authoring guidelines (where a skill owns one)
└── checklists/          # supporting checklists / shared reference docs (where applicable)

One predictable entry filename means an agent (or tool) pointed at skills/ knows where every skill starts; everything else in a skill directory is progressive-disclosure material referenced from its SKILL.md.

Design principles

• Durable state over context — anything that must survive compaction or a crash goes to disk (run ledgers, snapshots, reports), never only in context.
• External verification over self-assessment — compilers, tests, and live systems are the arbiters; an agent's claim of "done" without evidence is treated as not done.
• Judgment independence — review happens in a fresh context where possible, and always argues from what is on disk rather than memory of writing it.
• Deterministic before LLM — cheap, exit-code-gated scripts handle everything mechanical (drift detection, toolchain checks) so model judgment is spent only where judgment is required.
• Progressive disclosure — hub files stay small; mode files, guidelines, and checklists load only when needed.
• Proportional rigor — every heavyweight phase is opt-out, so a one-line fix doesn't pay a ten-phase tax.
• Commit by audit value, ignore only regenerable bulk — a multi-session build's memory (tickets, ledger, ADRs, run records) is committed under docs/; only regenerable logs are gitignored. Deriving something means checking it with a script, never maintaining it by hand.

Upgrading from 0.1

0.2.0 adds committed build memory and is backward-compatible: a repo opts in only by the presence of docs/build/README.md containing <!-- build-memory: v2 -->. A repo without that marker runs in legacy scratch mode — byte-for-byte the 0.1.0 behaviour (gitignored ledgers under .agents/scratch/, the old tickets_dir default), and every existing input keeps its name and default.

To adopt the committed layout in a repo:

• A fresh build — decompose-spec calls build-memory init during seeding; nothing extra to do.
• An existing repo — invoke build-memory init to write the layout (idempotent; never clobbers a file), then check to validate.
• An in-flight build with a legacy .agents/scratch/ — invoke build-memory migrate (dry-run by default; apply=true to perform). It moves run ledgers → docs/build/runs/<ID>.md, PR bodies/tools/fixtures into place, converts the machine ledger to docs/build/LEDGER.md, and records the rename mapping — move/rename only, contents byte-identical, history never renamed. Legacy ledgers still drive; on nextTicket: CAPSTONE a legacy ledger converts to the tail via decompose-spec mode=extend.

See CHANGELOG.md for the full 0.2.0 list and skills/build-memory/layout.md for the layout contract.

Authoring a new skill

1. Create skills/<name>/SKILL.md with frontmatter: name, description (what it does and when to use it), and inputs (each with name, required, description). Keep the body harness-neutral — no tool-specific directives in skill files.
2. Write instructions that are concrete enough to verify ("run X, expect exit 0"), and calibrated to a frontier model: specify what and why, not keystroke-level how.
3. If the skill nears the spec's ~500-line ceiling for SKILL.md or has distinct modes, split into a hub + modes/ files (see agent-docs).
4. Shell helpers go in scripts/: bash 3.2-compatible, self-contained, read-only by default — anything mutating must say so in its header, and known limitations belong in the header too.
5. No assumptions about repo, language, or toolchain anywhere: discover from the repo or take it as an input.

Related

• Agent Skills — the open format these skills conform to.
• anthropics/skills — Anthropic's reference collection; mostly capability skills (documents, design, testing tools).
• obra/superpowers — a full interactive development methodology (brainstorm → plan → subagent-driven TDD). Kindred spirit, different center of gravity: superpowers optimizes the human-in-the-loop workflow; agent-skills optimizes the autonomous run and its evidence trail.
• claude-hibernate — hibernate running Claude Code sessions across reboots. Began in this repo; Claude Code-specific by nature, so it lives on its own.

License

MIT