# agent-skills
[](https://skills.sh/v60samurai/agent-skills)
Skills and hooks for Claude Code that make the agent brief itself before it builds.
The flagship is **prompt-compile**: a define-do-verify loop that compiles a high-quality, task-specific prompt before executing any medium-or-larger task — automatically, on every prompt you submit.
## The problem
The best results from a coding agent come from the prompts experienced operators hand-write before big tasks: explicit non-goals, concrete targets, named skills in sequence, human checkpoints, verifiable pass/fail criteria.
Nobody writes that prompt for every task. So most tasks run on a one-liner, and quality tracks the prompt, not the model.
The obvious fix — "always plan before you build" in your CLAUDE.md — fails twice:
1. **Instructions decay.** Prose rules compete with everything else in context and lose.
2. **Self-grading is corruptible.** The same model that wants to skip overhead decides whether a task is "big enough" to deserve the overhead. "This one's simple" is the easiest rationalization there is.
## The system
Two parts, deliberately split:
| Part | What | Why it's this and not the other thing |
|------|------|----------------------------------------|
| `hooks/prompt-compile-gate.sh` | Dumb bash classifier, runs on every prompt via the `UserPromptSubmit` hook | Deterministic. Fires every time. Cannot rationalize. |
| `skills/prompt-compile/SKILL.md` | The 7-section brief recipe the model follows when the gate fires | The judgment lives where judgment belongs — in the model, guided by a written procedure. |
### The flow
```
your prompt
│
▼
gate (bash, deterministic)
│
├─ low band ──────────► executes directly, no overhead
│
├─ medium band ───────► compiles 7-section brief → shows you (non-blocking)
│ → executes in a FRESH subagent → verifies against brief
│
└─ high band ─────────► compiles brief → WAITS for your approval → executes → verifies
```
### The bands
| Band | Trigger | Behavior |
|------|---------|----------|
| **low** | no build verb, or trivial | silent — zero overhead |
| **medium** | build verb + a concrete surface ("polish the checkout **screen**", "add the auth **endpoint**") | brief compiled, shown, execution starts immediately; you interrupt if it's wrong |
| **high** | big/foggy/long signals ("entire", "from scratch", "not sure how", >45 words) | brief compiled, execution blocked on your OK |
Always silent: bug reports (your debugging workflow owns those) and explicit escapes (`just do X`, `skip the flow`).
### The brief — 7 sections, all required
1. **TASK + NON-GOALS** — what changes, what is explicitly preserved. Non-goals are the highest-value words in the brief.
2. **TARGET** — concrete environment, not adjectives. "~402pt logical width, Dynamic Island" — never "mobile-friendly".
3. **CONSTRAINT SOURCES** — files to read before generating anything. Missing source → stop and flag, never invent.
4. **SKILL SEQUENCE** — skills named in execution order. The executor must not rediscover routing.
5. **CHECKPOINTS** — where execution stops for your confirm. "No checkpoints" must be said explicitly.
6. **VERIFY** — observable pass/fail criteria, walked line by line after execution.
7. **OUTPUT CONTRACT** — the shape of the final response, in order.
### Why fresh-subagent execution
The compiled brief earns most of its value crossing a context boundary. A clean context executing a complete brief beats a long session executing a vague intention — no accumulated confusion, and everything the executor knows is exactly what the brief says. Briefs with human checkpoints run inline (subagents can't pause to ask you), or as one subagent per inter-checkpoint segment.
## Install
### As a Claude Code plugin (recommended — installs the hook too)
```
/plugin marketplace add v60samurai/agent-skills
/plugin install v60samurai-skills@v60samurai
```
The plugin registers the gate hook automatically — no settings.json editing. This is the "subscribe" install: a managed bundle that updates when new versions ship.
### Via skills.sh (copies skills so you can hack on them)
```bash
npx skills@latest add v60samurai/agent-skills
```
This installs the skills into Claude Code, Codex, and other Agent-Skills-standard harnesses, but **not the hook** — copy it yourself:
```bash
cp hooks/prompt-compile-gate.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/prompt-compile-gate.sh
```
Then register it in `~/.claude/settings.json`:
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/prompt-compile-gate.sh" }
]
}
]
}
}
```
The hook requires `jq` (`brew install jq` / `apt install jq`). Without the hook the skill still works — you just invoke it by hand instead of getting the deterministic trigger, which is half the point.
## Repo structure
```
skills/
workflow/ # process systems: how the agent works
prompt-compile/
SKILL.md
hooks/
prompt-compile-gate.sh
hooks.json # plugin hook registration
.claude-plugin/
marketplace.json # /plugin marketplace add v60samurai/agent-skills
plugin.json # skill + hook manifest
```
Adding a skill = drop `skills/<category>/<name>/SKILL.md` in. skills.sh discovers it automatically; the plugin needs its path added to the `skills` array in `.claude-plugin/plugin.json` (one line). New skills earn a place in `skills/` by being used daily on real work first — unproven experiments live in `skills/in-progress/` until they graduate.
## Tune it
The gate is a heuristic — word lists at the top of the script:
- `verbs` — what counts as a build/change request
- `surface` — what makes a request medium (naming a concrete thing: screen, endpoint, component…)
- `big` / `fog` — what escalates to high
- The `>45 words` threshold for long prompts
Run the gate by hand to test your changes:
```bash
printf '{"prompt": "polish the checkout screen for mobile"}' | bash hooks/prompt-compile-gate.sh
```
Empty output = silent. Otherwise the JSON names the band.
## Skills
| Skill | What it does |
|-------|--------------|
| [`prompt-compile`](skills/workflow/prompt-compile/SKILL.md) | Compile a 7-section task brief before executing; define-do-verify with fresh-context execution |
More coming. The bar for inclusion: used daily on real work first.
## Contributing
Gate misfires are the most valuable thing you can file — the exact prompt, the band you got, the band you expected. Issue templates are set up for that, skill proposals, and bugs. PR and merge rules live in [CONTRIBUTING.md](CONTRIBUTING.md): one change per PR, new skills start in `skills/in-progress/`, gate changes ship with routing test output, squash merges only.
## License
[MIT](LICENSE)