|
| 1 | +# Second Pass |
| 2 | + |
| 3 | +**A universal skill enhancement layer.** Sees the skill being invoked, the user's input, the produced output — and judges based on what the skill should have achieved. Returns a grade and concrete feedback, drives a revision loop, ships a better artifact. |
| 4 | + |
| 5 | +Works across **any** Claude Code skill whose output is judged rather than tested. The judge is not bound to a single domain — it reads the originating skill's `SKILL.md` on the fly, infers what success looks like for that specific skill, and grades against that intent. Verified across writing, design, planning, structural documents, and code. |
| 6 | + |
| 7 | +## What problem it solves |
| 8 | + |
| 9 | +Most Claude Code skills produce outputs that have no automatic quality floor. A test either passes or fails, a deploy either succeeds or fails — those are measurable. But a LinkedIn post, a proposal, an implementation plan, a designed landing page, a SKILL.md you just authored, an architecture write-up — those are judged, not tested. If the skill produces a weak output on the first pass, the user ships the weak output. |
| 10 | + |
| 11 | +The naive fix is to write a critic for each skill: a writing critic, a design critic, a plan critic. That doesn't scale — there are hundreds of public skills, and most users won't author their own critic for each one they install. |
| 12 | + |
| 13 | +Second Pass takes the universal route. **One skill enhancement layer that adapts to whatever skill produced the output.** It reads the originating skill, understands its intent, and applies a single A–F rubric grounded in *that* skill's standards. Same machinery for `internal-comms`, `frontend-design`, `writing-plans`, `proposal-writer`, or any community skill from `obra/superpowers`, `anthropics/skills`, or `ComposioHQ/awesome-claude-skills`. |
| 14 | + |
| 15 | +## How it works |
| 16 | + |
| 17 | +1. Claude finishes a task using one or more skills (or directly). |
| 18 | +2. If the output is non-measurable (writing, plan, explanation, proposal, design, etc.), Claude auto-invokes Second Pass. |
| 19 | +3. Second Pass reads the originating skill's `SKILL.md` to understand what "good" looks like for *this specific skill*, then spawns the `self-judge` subagent with three inputs: skill(s) used, user request, output. |
| 20 | +4. The subagent grades the output (A, B, C, D, or F) on a universal rubric grounded in skill intent + user request, and returns concrete drop-in feedback. |
| 21 | +5. If the grade meets the passing bar, the output ships with the grade attached. If not, Claude revises using the feedback (and optionally re-judges, in strict mode). |
| 22 | +6. Status line tells the user what is happening: `Second Pass [attempt 1/3]: grading output...` → `passed at attempt 1/3 (grade B).` |
| 23 | + |
| 24 | +No user invocation required. It auto-triggers based on output type, then steps out of the way. |
| 25 | + |
| 26 | +## Why a universal layer (vs. per-skill critics) |
| 27 | + |
| 28 | +The first instinct when you want better skill outputs is to write a critic for each skill. That instinct is wrong at scale: |
| 29 | + |
| 30 | +- **You don't own the skills.** Most installed skills come from `obra/superpowers`, `anthropics/skills`, community awesome-lists. You can't author a critic for each one. |
| 31 | +- **Per-skill critics drift.** When the source skill updates, the critic doesn't. |
| 32 | +- **Critics that hardcode rules become a maintenance burden.** The judge that reads `SKILL.md` on the fly stays correct as long as the skill's own description is correct. |
| 33 | + |
| 34 | +Second Pass spends a fixed token budget on the universal grader, then reads each target skill's intent live. One layer, every skill. |
| 35 | + |
| 36 | +## Install |
| 37 | + |
| 38 | +Second Pass ships as three installable pieces. The skill itself, the slash commands, and the config file live in separate Claude Code directories by convention — see the steps below. |
| 39 | + |
| 40 | +### 1. Install the skill |
| 41 | + |
| 42 | +Copy or symlink this folder to `~/.claude/skills/second-pass/`: |
| 43 | + |
| 44 | +```bash |
| 45 | +# macOS / Linux |
| 46 | +ln -s "/path/to/second-pass" ~/.claude/skills/second-pass |
| 47 | + |
| 48 | +# Windows (PowerShell, admin or dev mode enabled) |
| 49 | +New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\second-pass" -Target "C:\path\to\second-pass" |
| 50 | +``` |
| 51 | + |
| 52 | +### 2. Install the slash commands (separate step) |
| 53 | + |
| 54 | +Claude Code loads slash commands from `~/.claude/commands/`, not from the skill folder. You must install these separately — copy the three files from this skill's `commands/` directory: |
| 55 | + |
| 56 | +```bash |
| 57 | +# macOS / Linux |
| 58 | +mkdir -p ~/.claude/commands/second-pass |
| 59 | +cp commands/*.md ~/.claude/commands/second-pass/ |
| 60 | + |
| 61 | +# Windows (PowerShell) |
| 62 | +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\commands\second-pass" | Out-Null |
| 63 | +Copy-Item commands\*.md "$env:USERPROFILE\.claude\commands\second-pass\" |
| 64 | +``` |
| 65 | +
|
| 66 | +This registers `/second-pass:passing-grade`, `/second-pass:iteration-cap`, and `/second-pass:reset` with Claude Code. |
| 67 | +
|
| 68 | +### 3. Config (auto-managed) |
| 69 | +
|
| 70 | +The config file at `~/.claude/second-pass/config.json` is created the first time you run any slash command. Until then, defaults apply (`passing_grade: B`, `iteration_cap: 3`). See `examples/` for preconfigured setups (strict, default, lenient). |
| 71 | +
|
| 72 | +## Configuration |
| 73 | +
|
| 74 | +### Passing grade |
| 75 | +
|
| 76 | +``` |
| 77 | +/second-pass:passing-grade A |
| 78 | +/second-pass:passing-grade B |
| 79 | +/second-pass:passing-grade C |
| 80 | +/second-pass:passing-grade D |
| 81 | +/second-pass:passing-grade F |
| 82 | +``` |
| 83 | +
|
| 84 | +Setting the bar to `A` makes Second Pass strict — most first drafts will trigger revisions. Setting it to `D` or `F` effectively disables revisions. `B` is the recommended default. |
| 85 | +
|
| 86 | +### Iteration cap |
| 87 | +
|
| 88 | +``` |
| 89 | +/second-pass:iteration-cap 3 # default |
| 90 | +/second-pass:iteration-cap 5 # allow more revision attempts |
| 91 | +/second-pass:iteration-cap 1 # disable iteration — one grading pass, then ship |
| 92 | +``` |
| 93 | +
|
| 94 | +Higher caps mean more revisions per output (more tokens). Lower caps mean faster delivery but more outputs may ship below bar. A cap of `1` disables iteration entirely. |
| 95 | +
|
| 96 | +### Confirm revisions (re-judge after revising) |
| 97 | +
|
| 98 | +``` |
| 99 | +/second-pass:confirm-revisions true # re-judge after revision in a loop (more tokens, more confidence) |
| 100 | +/second-pass:confirm-revisions false # default — apply feedback once, ship without re-judging |
| 101 | +``` |
| 102 | +
|
| 103 | +By default, when a baseline grades below the bar, Second Pass applies the judge's feedback once and ships. The judge already gave specific drop-in replacements; trust them. Set `confirm_revisions: true` only for high-stakes artifacts where you want the loop to verify the lift before shipping. |
| 104 | +
|
| 105 | +### Presets |
| 106 | +
|
| 107 | +``` |
| 108 | +/second-pass:strict # bar A, cap 5, confirm-revisions true — high-stakes proposals, public copy |
| 109 | +/second-pass:lenient # bar C, cap 2, confirm-revisions false — quick drafts, speed beats polish |
| 110 | +``` |
| 111 | +
|
| 112 | +These shortcuts overwrite the full config in one call. |
| 113 | +
|
| 114 | +### Reset to defaults |
| 115 | +
|
| 116 | +``` |
| 117 | +/second-pass:reset |
| 118 | +``` |
| 119 | +
|
| 120 | +Restores all settings to defaults (`passing_grade: B`, `iteration_cap: 3`, `confirm_revisions: false`). Use when your config is in an unexpected state or after experimenting with stricter bars. |
| 121 | +
|
| 122 | +## Optional: reinforce auto-trigger in your CLAUDE.md |
| 123 | +
|
| 124 | +Second Pass's skill description tells Claude to auto-invoke before returning non-measurable outputs, and that is usually enough. If you want a belt-and-suspenders guarantee, add this line to your user or project `CLAUDE.md`: |
| 125 | +
|
| 126 | +``` |
| 127 | +Before returning any non-measurable output (writing, proposals, plans, explanations, designs, drafts), invoke the Second Pass skill to self-judge and iterate until the configured passing bar is met. |
| 128 | +``` |
| 129 | +
|
| 130 | +## Skill compatibility — what Second Pass enhances |
| 131 | +
|
| 132 | +Second Pass works against any skill whose final output is **judged, not tested**. Verified across 6 tests on 5 distinct output types (text writing, code/visual design, structural documents, implementation plans, voice content). Below is the high-value pairing list from popular public skill libraries. |
| 133 | +
|
| 134 | +### High-value pairings (use Second Pass) |
| 135 | +
|
| 136 | +| Skill | Source | Output type | Why it benefits | |
| 137 | +|---|---|---|---| |
| 138 | +| `internal-comms` | anthropics/skills | 3P updates, FAQs, newsletters | Strict format + 1-3 sentence rule. Verified B → A lift. | |
| 139 | +| `brand-guidelines` | anthropics/skills | Branded text/styled artifacts | Tone consistency, no AI tells. | |
| 140 | +| `frontend-design` | anthropics/skills, plugin | Web components, landing pages | Catches generic AI aesthetics. | |
| 141 | +| `skill-creator` | anthropics/skills | SKILL.md files | Trigger clarity, frontmatter discipline. | |
| 142 | +| `content-research-writer` | ComposioHQ/awesome-claude-skills | Researched long-form | Citations, hook quality, AI tells. | |
| 143 | +| `tailored-resume-generator` | ComposioHQ/awesome-claude-skills | Resumes | Specificity over fluff. | |
| 144 | +| `superpowers:brainstorming` | obra/superpowers | Design exploration notes | Output coherence. | |
| 145 | +| `superpowers:writing-plans` | obra/superpowers | Implementation plans | Plan completeness, step clarity. | |
| 146 | +| `write-like-ahmed`, `proposal-writer` | (custom) | Voice writing | AI-tell stripping, voice fidelity. | |
| 147 | +| `humanizer` | (custom) | De-AI'd text | Cross-check voice rules held. | |
| 148 | +
|
| 149 | +### Skip (measurable output) |
| 150 | +
|
| 151 | +| Skill | Why skip | |
| 152 | +|---|---| |
| 153 | +| `superpowers:executing-plans` | Output is code/diff. Tests verify, not judges. | |
| 154 | +| `superpowers:test-driven-development` | Pass/fail tests = measurable. | |
| 155 | +| `superpowers:systematic-debugging` | Bug fixed or not — measurable. | |
| 156 | +| `webapp-testing`, `mcp-builder`, `claude-api` | Code that compiles or runs — measurable. | |
| 157 | +| `n8n-build`, `agent-browser`, `nano-banana` | API responses, image generation success — measurable. | |
| 158 | +| `init`, `review`, `security-review` | Audit findings produce diffs/issues — measurable. | |
| 159 | +
|
| 160 | +If you're unsure, ask: *can I name a concrete pass/fail check for this output?* If yes — skip Second Pass. If no — use it. |
| 161 | +
|
| 162 | +## What it does not do |
| 163 | +
|
| 164 | +- **Does not generate content.** It only grades existing outputs and drives revision. |
| 165 | +- **Does not rewrite drafts unilaterally.** Feedback flows back to the calling agent, which revises. |
| 166 | +- **Does not cache rules per skill.** Grading reads skill intent on the fly; no rule database. |
| 167 | +- **Does not fire on measurable outputs.** Test results, deploys, compile output, API codes are out of scope. |
| 168 | +- **Does not require manual invocation.** It triggers itself based on output type. |
| 169 | +
|
| 170 | +## Grading rubric |
| 171 | +
|
| 172 | +- **A** — meets skill intent fully, serves the request precisely, no AI tells, concrete and clear |
| 173 | +- **B** — meets intent with minor gaps, serves the request well, one or two small issues |
| 174 | +- **C** — partial intent match or missed asks, noticeable issues |
| 175 | +- **D** — significant gaps, wrong tone or format, missing key content, or strong AI smell |
| 176 | +- **F** — does not meet intent or misses the request; rewrite from scratch |
| 177 | +
|
| 178 | +Default passing bar: `B`. |
| 179 | +
|
| 180 | +## Files |
| 181 | +
|
| 182 | +``` |
| 183 | +second-pass/ |
| 184 | +├── SKILL.md Entry point — flow, auto-trigger rules, status format |
| 185 | +├── README.md This file |
| 186 | +├── CHANGELOG.md Release notes, follows Keep a Changelog / semver |
| 187 | +├── LICENSE MIT |
| 188 | +├── agents/ |
| 189 | +│ └── self-judge.md Subagent that does the grading |
| 190 | +├── commands/ |
| 191 | +│ ├── passing-grade.md /second-pass:passing-grade (install to ~/.claude/commands/second-pass/) |
| 192 | +│ ├── iteration-cap.md /second-pass:iteration-cap |
| 193 | +│ └── reset.md /second-pass:reset |
| 194 | +└── examples/ |
| 195 | + ├── README.md Explains the three preconfigured setups |
| 196 | + ├── config-default.json B bar, cap 3 — recommended |
| 197 | + ├── config-strict.json A bar, cap 5 — for high-stakes output |
| 198 | + └── config-lenient.json C bar, cap 2 — for quick drafts |
| 199 | +``` |
| 200 | +
|
| 201 | +## License |
| 202 | +
|
| 203 | +MIT — see [`LICENSE`](LICENSE). Use it, fork it, improve it. |
0 commit comments