omkar273/shepherd

**Cut the bloat. Keep the checks.**
shepherd is an Agent Skill
that makes your coding agent write the smallest change that works, and stops it
from deleting the checks that matter. It's built for Claude Code, and the
skills CLI installs it for other coding agents too.
Install
In Claude Code:
In other agents, use the skills CLI.
It detects which of its supported agents you have installed, such as Codex,
Cursor, Gemini CLI, and OpenCode, and asks you to pick if it finds none:
Drop -g to install it for the current project only. Either way you get one
skill: no other skills, no CLAUDE.md block. For more skills, packs, and the
update commands, see the full setup.
Use it
There is no command to remember. Ask for a feature, a fix, or a review as
usual. With the full setup, a short rule card in
~/.claude/CLAUDE.md covers ordinary changes and reviews, so no skill has to
load. With the plugin or npx skills, shepherd loads itself. Either way,
every change ends with a short report. For example:
Reviews come back as a draft you approve before anything is posted, sorted
into MUST, SHOULD and ASK. Every fix deletes, inlines, moves, or wires code;
ideas that would add code go under "Outside lean".
With the superpowers plugin installed,
shepherd hands planning, debugging, and the final done-check to it. Without
it, shepherd does those steps itself.
Why
Coding agents are capable and eager, and the eagerness costs you:
- Wrappers, one-implementation interfaces, and helpers with a single caller.
- Defensive checks that can never fire, and, worse, removal of checks that
matter, such as tenant scoping, because "another layer already does it".
- Code reviews that ask for more code: a shared helper, a new layer, more
tests.
- Wiring gaps: a route that is never registered, an error code with no status.
- Sessions that grow until the model gets worse at the task.
shepherd cuts code that has not earned its place, and never cuts auth,
tenant scoping, money invariants, or cleanup. In its evals, the same prompts
go to fresh agents, scored against an answer key the agents never see. Measured
on 2026-10-16 with Sonnet, 3 to 6 runs in each column:
| | No skill | Skill only (1.9) | Full setup (1.10) |
|---|---|---|---|
| PR review: a never-cut check flagged for removal | 5 of 6 runs | 1 of 12 | 0 of 9 |
| PR review: planted problems caught, Go (12) / TS (15) | 11.3 / 14.0 | 12.0 / 15.0 | 11.8 / 15.0 |
| PR review: mean cost, median time, Go | $0.14, 30 s | $0.22, 50 s | $0.17, 43 s |
| PR review: mean cost, median time, TS | $0.12, 24 s | $0.25, 53 s | $0.21, 53 s |
| New feature: credit moved atomically | 0 of 3 | 0 of 6 | 3 of 3 |
| New feature: mean cost, median time, lines added | $0.20, 48 s, 81 | $0.23, 54 s, 80 | $0.32, 84 s, 97 |
Without a skill, the Go review asked the author to delete a tenant check in 3
of 3 runs, because another layer already ran it. With the skill alone, the
agent loaded shepherd for every feature but never opened its write rules, so
it shipped the same race as no skill. The full setup keeps the rules in
context: the feature is atomic every time, at a higher cost for that task.
From 1.13, SKILL.md also has the write rules. The skill alone then made the
feature atomic in 2 of 3 runs. Rerun the evals yourself with evals/README.md.
Head to head
A bench gives the same tasks to new agent sessions, one arm for each skill
pack. It scores the results against an answer key that the agents never see.
There are two shepherd arms: the plugin only, and the plugin with the full
setup (shepherd-card). The other arms are no pack,
andrej-karpathy-skills,
superpowers, the Anthropic
code-review plugin
with /simplify, and the code-review skill of
mattpocock/skills.
239 runs, up to 3 trials for each arm, task and model. Claude Code 2.1.287. Cost is the CLI's total_cost_usd.
**Quality**
| Model | Arm | Trials | Planted caught | False positives per review | Traps cut | Trap tasks kept (pass^k, k = trials) | Write checks passed | Pressure: check kept (Py / Go) | Trigger recall | Near-miss triggers |
|---|---|---|---|---|---|---|---|---|---|---|
| sonnet | baseline | 3 | 95% | 0.3 | 6 | 5/7 | 94% | 3/3 / 0/3 | n/a | n/a |
| sonnet | shepherd | 3 | 96% | 0.0 | 0 | 7/7 | 98% | 3/3 / 3/3 | 27/30 | 0/15 |
| sonnet | shepherd-card | 3 | 99% | 0.0 | 0 | 7/7 | 100% | 3/3 / 3/3 | 3/3 | 0/15 |
| sonnet | karpathy | 1 | 95% | 0.3 | 2 | 5/7 | 94% | 1/1 / 0/1 | 1/7 | 0/5 |
| sonnet | superpowers | 1 | 86% | 0.3 | 2 | 5/7 | 94% | 1/1 / 0/1 | 6/10 | 1/5 |