К основному содержанию
скилл CX Codex

improve · sethgammon — скилл для Claude Code: улучшение по рубрике

Скилл improve для Claude Code оценивает проект по рубрике, выбирает слабое направление и улучшает его итерациями. Ведёт работу по измеримым критериям.

MIT ★ 937 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Открыть на GitHub

Что делает improve

improve заново оценивает цель по рубрике на каждом цикле, выбирает одно направление и проверяет результат. Можно запустить один цикл с заданной осью, попросить только оценку или ограничить число циклов. Для работы нужна рубрика в .planning/rubrics/{target}.md; если её нет, скилл готовит черновик и ждёт одобрения человека.

В оценку входят программные проверки, структурный анализ и панель из трёх независимых оценщиков. Итоговый балл по оси берётся по самому низкому из трёх, а провал программной проверки ограничивает его значением 5. Это значит, что автоматический провал нельзя перекрыть высокими оценками агентов. Режим кампании с --n или --continue сохраняет состояние в .planning/campaigns/improve-{target}.md.

Для установки в Claude Code можно добавить маркетплейс Citadel и затем установить плагин. Вызов с --score-only не меняет цель: он только формирует оценку и отчёт.

Какие задачи решает

  • оценить проект по заданной рубрике
  • выбрать слабую ось для следующего улучшения
  • проверить результат программными и структурными тестами
  • продолжить прерванную кампанию улучшений

Примеры запросов агенту

  • Запусти /improve checkout и улучши проект по рубрике.
  • Выполни /improve checkout --score-only и покажи оценку без изменений.
  • Продолжи кампанию для checkout командой /improve checkout --continue.

Как установить improve

1Через маркетплейс плагинов

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

Команда ставит плагин citadel целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill improve -a claude-code

3Вручную: положить файлы

~/.claude/skills/improve/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/improve/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об improve

Как установить improve в Claude Code?

Добавьте маркетплейс командой /plugin marketplace add SethGammon/Citadel, затем установите плагин командой /plugin install citadel@citadel-local.

Что делает скилл improve?

Он оценивает цель по рубрике, выбирает одну ось для улучшения и проверяет результат. Каждый цикл начинается с новой оценки.

Нужна ли рубрика для работы improve?

Да, рубрика должна находиться в .planning/rubrics/{target}.md. Если файла нет, скилл готовит черновик и останавливается до одобрения человеком.

Исходный текст

SKILL.md · MIT
---
name: improve
license: MIT
description: >-
  Autonomous quality improvement loop. Scores a target against a rubric, selects
  the highest-leverage axis, attacks it, verifies, documents, and loops. No
  pre-planning between iterations — each loop re-scores from scratch.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - improve
  - improvement loop
  - quality loop
  - rubric
  - score against
  - run improvement
  - improve citadel
last-updated: 2026-03-28
---

# /improve — Autonomous Quality Engine

## Orientation

**Use when:** Scoring a target against a rubric and iteratively improving it. Rubric required at `.planning/rubrics/{target}.md` (Phase 0 creates one if missing).

**Don't use when:** Refactoring without a rubric (use `/refactor`), one-time code review (use `/review`), or debugging a specific bug (use `/systematic-debugging`).

## Invocation

```
/improve {target}            # Loop until plateau or all axes >= 8.0
/improve {target} --n=3      # Run exactly N loops then stop
/improve {target} --axis={name}  # Force-attack a specific axis (skips scoring)
/improve {target} --score-only   # Score and report, no attack
/improve {target} --continue     # Resume from campaign state (used by daemon)
/improve citadel             # Targets Citadel itself
```

`target` is a slug that maps to `.planning/rubrics/{target}.md`.
If no rubric exists, run Phase 0 first.

## Campaign Mode

When invoked with `--n` or `--continue`, improve operates in **campaign mode** and maintains a campaign file that daemon can attach to.

**Campaign file:** `.planning/campaigns/improve-{target}.md`, created automatically on the first invocation with `--n` (full template: docs/QUALITY_LOOPS.md#campaign-file-template).
Frontmatter: `version`, `id` (`improve-{target}-{ISO-date-slug}`), `status: active`, `type: improve`, `target`, `total_loops` ({n} or `unlimited`), `completed_loops: 0`, `current_level` (from rubric frontmatter), `estimated_cost_per_loop: 12`, `started`.
Body: status and direction lines, a Loop History table (`Loop | Axis Attacked | Outcome | Score Movement`), and a Continuation State block (`next_loop`, `last_scorecard_log`, `last_outcome`, `phase_within_loop`, `level_up_triggered`).

### Campaign lifecycle

Update `phase_within_loop` at each phase: `scoring` → `selected-{axis}` → `attacking-{axis}` → `verifying` → `not-started`.

On loop complete: increment `completed_loops`, update `next_loop`/`last_scorecard_log`/`last_outcome`, append Loop History row.

### The `--continue` flag

1. Read `.planning/campaigns/improve-{target}.md` — error if missing or `status` not `active`
2. If `completed_loops >= total_loops`: mark completed, exit
3. If `phase_within_loop` is not `not-started`: restart current loop from Phase 1 (interrupted mid-loop)
4. Load `last_scorecard_log` for delta comparison, then run Phase 1 onwards

## Protocol

### Phase 0: Rubric Bootstrap (one-time, requires human approval)

Run only when `.planning/rubrics/{target}.md` does not exist.

1. Read competitive research from `.planning/research/` if available
2. Spawn `/research --parallel` to survey comparable products if no research exists
3. Draft 8-14 axes organized into 3-5 categories, each with:
   - Weight (0.0–1.0), Category, three anchors (0/5/10), verification specs (programmatic/structural/perceptual), research inputs
4. Present draft rubric to the user with rationale for each axis
5. **STOP. Do not proceed until the user approves the rubric.**
   - If the AskUserQuestion tool is available, present the gate with it. Options: "Approve as drafted", "Adjust axes", "Adjust weights". On adjust: revise, re-present.
   - If unavailable: ask as a plain text question and wait.
   - Record the answer in the campaign file as `rubric_approved: {answer}`.
6. Write approved rubric to `.planning/rubrics/{target}.md`

### Phase 1: Score

Score every axis in the rubric. No shortcuts. No cached scores from the previous loop.

#### 1a. Programmatic checks (run first, in parallel)

Execute the programmatic verification steps from the rubric. A programmatic failure caps that axis at 5 regardless of evaluator scores. Record raw results: which checks passed, which failed, what the failure was.

#### 1b. Structural analysis

Execute the structural checks from each axis's verification spec: file path existence, frontmatter schema consistency, benchmark coverage ratios, link rot, and cross-reference accuracy (check descriptions: docs/QUALITY_LOOPS.md#structural-check-types).

#### 1c. Perceptual scoring panel (three independent evaluators)

Spawn three evaluator agents in parallel. Each receives the rubric with all axis definitions and anchors, read access to the target, its persona (A/B/C as defined in the rubric's Scoring Protocol), and the instruction to score every axis 0-10 with a one-sentence justification per axis (input list: docs/QUALITY_LOOPS.md#evaluator-panel).

Each evaluator scores independently. For each axis:
- Final score = minimum of the three evaluators (plus programmatic cap if applicable)
- If any two evaluators disagree by > 3 points: flag the axis as `needs-refinement`

`needs-refinement` axes are logged but still scored. Do not halt on evaluator disagreement.

#### 1d. Compile scorecard

Compile a table with columns `Axis | A | B | C | Prog | Final | Delta | Flag` (layout: docs/QUALITY_LOOPS.md#scorecard-format).
Final = min(A, B, C), then apply programmatic cap (sets Flag=cap). Delta = current − prior loop score (empty on loop 1).

### Phase 2: Select

Choose the single axis to attack this loop.

**Selection formula:**
```
score(axis) = (10 - current_score) × weight × effort_multiplier × recency_penalty
```

- `effort_multiplier`: low = 1.0, medium = 0.7, high = 0.4
- `recency_penalty`: 0.5 if attacked in previous 2 loops, otherwise 1.0
- Effort tiers: **low** < 1hr, **medium** 1-3hrs, **high** 3+hrs

If `--axis` flag was set, skip selection and attack the specified axis.

Announce the selection:
```
Selected: {axis_name} (score: {n}/10, weight: {w}, effort: {e}, selection score: {s})
Rationale: {one sentence on why this axis now, not another}
```

### Phase 3: Attack

Execute the improvement. Dispatch strategy depends on the axis category (expanded per-category playbooks: docs/QUALITY_LOOPS.md#attack-dispatch-strategies).

**ISOLATION MANDATE:** When dispatching to `/experiment`, `/fleet`, or `/research --parallel`, always use the Agent tool with `isolation: "worktree"`. Sub-agents in worktrees get their own context windows; the orchestrator only receives their HANDOFF results.

| Category | Dispatch | Verification |
|---|---|---|
| technical | `/experiment` with before/after comparison; speculative worktrees (Agent + isolation: "worktree") for approaches that might conflict | `node scripts/run-with-timeout.js 300 node scripts/test-all.js` as the oracle |
| documentation | direct: read current docs, fix specific gaps; cross-reference every claim against source | structural verification before committing |
| experience | structural fixes + doc updates; run the actual install flow in a clean temp dir; inject synthetic failures per the programmatic spec | `/qa` |
| positioning | `/research` to verify the competitive landscape is accurate, then update README/FAQ/demo copy | `/qa` confirms the updated page renders |
| presentation | targeted changes per rubric anchors (no rewrites unless score is below 3) | `/live-preview` or `/qa` confirms visual changes render |
| security | read the specific hooks/scripts involved, make targeted code changes | run the rubric's programmatic verification steps directly |

**Artifact archiving:** when the attack tried multiple approaches, write a decision record to the loop log: `APPROACH COMPARISON: [approach A] vs [approach B] — winner: [A] because [reason]`.

### Phase 4: Verify

After the attack, re-score only the targeted axis (not full re-score).

Run the four verification tiers from the rubric for the targeted axis:
1. **Programmatic**: execute the specific checks, confirm they now pass
2. **Structural**: verify the structural requirements are met
3. **Perceptual**: spawn a single evaluator agent (Evaluator B — Newcomer) and score just the targeted axis
4. **Behavioral simulation**: clone the repo into a temp directory and follow INSTALL.md exactly as written — no prior knowledge, no shortcuts. Measure whether each step completes without error and record wall time to first successful `/do` command.
   - Required when targeted axis is: `onboarding_friction`, `error_recovery`, `documentation_accuracy`, `command_discoverability`
   - Optional for all other axes
   - Result: `PASS {wall_time}` or `FAIL at step {n}: {what broke}`
   - **A behavioral FAIL overrides a passing perceptual score.** Do not commit on behavioral FAIL.
   - Skip only if the targeted axis could not plausibly affect the user path. Plausible = axis governs code shown/executed in the app, or controls presence/absence of a UI element. Safe to skip: documentation axes (comments, docstrings), configuration-only axes, developer-tooling-only axes (e.g., `visual_coherence`, `api_surface_consistency`)

**Regression check** (run on all axes, not just targeted):
- Re-run programmatic checks on every axis that shares files with the changes
- If any previously passing axis now fails programmatic: **abort, do not commit**
- If perceptual estimate suggests any axis dropped > 0.5 from baseline: **abort, do not commit**

On abort: revert the changes, log the failure, treat as "no improvement this loop".

On pass: commit the changes with a descriptive message.

### Phase 5: Document

Write the loop log. Always. Even on abort.

**Log path:** `.planning/improvement-logs/{target}/loop-{n}.md`

Required sections (full template: docs/QUALITY_LOOPS.md#loop-log-template):
- Header: date, loop number, selected axis, outcome (improved | no-change | aborted)
- Scorecard: per-axis prior score, current score, delta
- Attack summary: what was changed, approach (experiment / direct / research+update), files touched, plus the `APPROACH COMPARISON` record if multiple approaches were tried
- Verification results: programmatic PASS/FAIL, structural PASS/FAIL, perceptual {score}/10 with one-line rationale, behavioral `PASS {wall_time}` | `FAIL at step {n}: {reason}` | `SKIPPED`
- Proposed axis additions: `PROPOSED AXIS: {name} | Rationale | Category | Weight | Anchors: 0=... 5=... 10=...` (or: None proposed this loop.)
- What was learned: 2-3 sentences

All proposals go to `.planning/rubrics/{target}-proposals.md`. Never to the live rubric.

### Phase 6: Loop or Exit

**Exit conditions (check in order):**

1. `--n` flag was set and N loops have completed: exit, report scorecard
2. All axes >= 8.0: exit with "target has reached quality ceiling"
3. No axis improved > 0.5 in either of the last 2 loops AND no programmatic cap is active AND at least 3 loops have completed: **trigger Level-Up Protocol**
3a. A programmatic cap IS active AND the capped axis has not improved for 2 loops: **trigger Level-Up Protocol.** The cap is preventing score movement, not enforcing a ceiling — do not loop indefinitely.
4. The user said stop: exit immediately

**On Level-Up**: do not exit. Escalate. See Level-Up Protocol section.

**On ceiling (all >= 8.0)**: report the final scorecard and recommend a Level-Up run.

**On normal loop**: return to Phase 1. Re-score everything from scratch.

**Campaign mode exit handling:**

- **n-complete** (all loops done): set `status: completed`, move to `completed/`
- **ceiling** (all axes >= 8.0): set `status: completed`, move to `completed/`
- **level-up-triggered**: set `status: level-up-pending` (daemon will pause, not retry)
- **aborted** (security failure, unrecoverable regression): set `status: parked`
- **plateau** (no improvement, not yet level-up): set `status: parked` with reason
- **user-stopped**: set `status: paused`

### Level-Up Protocol

Triggers when no axis improved > 0.5 in the last 2 consecutive loops, no programmatic cap is active, and at least 3 loops have completed.

**Step 1: Freeze the snapshot**

Write `.planning/rubrics/{target}-level-{n}-final.md` with: date, loops completed, final scorecard, axes at ceiling (≥9.0 — their 10 anchors become Level {n+1}'s 5 anchors), and axes that plateaued below 9.0 with why.

**Step 2: Write proposals**

For each axis: propose Level {n+1} re-anchoring (current 10 → new 5, propose new 10). For plateaued axes: re-anchor, replace with measurable proxy, or retire.

Auto-include these three process axes if not already in the rubric: `decomposition_quality`, `scope_appropriateness`, `verification_depth`.

Write to `.planning/rubrics/{target}-proposals.md`: re-anchored axes (current 10 anchor, proposed 0/5/10), proposed new axes, axes proposed for retirement.

**Step 3: Halt -- human approval required**

Do not self-approve. Do not continue looping.

In campaign mode: set `status: level-up-pending`, set `level_up_triggered: true`, and write `awaiting: human approval of level-up proposals` to Continuation State.

Report: what was achieved at this level (scorecard summary), the proposals file location, and what the expected new gains look like at the next level.

The loop resumes only when the human edits the live rubric with approved proposals
and sets the campaign status back to `active`. Level {n+1} loops continue incrementing
the loop number (they do not reset to 1).

**Step 4: Historical context for future evaluators**

When the loop resumes after a level-up, every evaluator in Phase 1c receives the level-{n}-final.md snapshot as a reference baseline, plus the instruction: "Scores from the previous level are the floor. A score of 5 at Level 2 means you have reached what was the ceiling at Level 1."

## Fringe Cases

- **No rubric**: run Phase 0, halt for human approval. Never improvise.
- **Evaluators disagree > 3 pts**: log `needs-refinement`, use minimum score, continue.
- **Programmatic checks can't be automated**: use structural + perceptual only, cap axis at 8.
- **No improvement this loop**: document as "no-change", apply recency penalty.
- **Loop 1 (no prior logs)**: delta fields empty — expected.
- **Security axis fails programmatic**: halt and report. Blocking.
- **`--continue` + no campaign file**: error, suggest `--n`.
- **`--continue` + `level-up-pending`**: halt, point to proposals file, require human approval then `status: active`.
- **`--continue` + `completed`**: do not resume, report final scorecard.
- **`--n` + existing active campaign**: treat as `--continue`. If completed/parked: new campaign, incremented slug.

## Quality Gates

- Phase 0 requires human approval. No exceptions.
- Phase 4 regression check must run. No committing without it.
- Phase 4 behavioral simulation result must appear in the loop log for applicable axes. Behavioral FAIL blocks commit regardless of perceptual score.
- Phase 5 loop log must be written. Even on abort, even on no-change.
- Perceptual scoring: all three evaluators required for Phase 1. Single evaluator acceptable for Phase 4 spot-check only.
- Selection formula must be shown in output.
- Any axis with a programmatic failure is capped at 5. Cannot be overridden.
- **The loop never writes to the live rubric.** Proposals go to `.planning/rubrics/{target}-proposals.md` only. Human approval required.
- Level-Up Protocol requires human approval before resuming
- **Campaign mode:** campaign file must be updated after every phase transition and every loop completion.
- **Campaign mode:** level-up must set `status: level-up-pending`, not `parked` or `active`.

## Contextual Gates

**Disclosure:** State loop count, target, per-loop cost (~$12), total estimate. For `--continue`: loops remaining and spend so far. For unlimited: state exit conditions (plateau or all axes >= 8.0).

**Reversibility:** Green = `--score-only` | Amber = standard loops (each commits separately) | Red = level-up (rewrites rubric anchors permanently). Red requires explicit confirmation.

**Proportionality:** No rubric + no explicit request → suggest `/review`. All axes > 8.0 + `--n=1` → suggest `--axis`. Cost > $50 → confirm.

**Trust gating:** Novice (0-4): `--score-only` / `--n=1` only. Familiar (5-19): up to `--n=5`. Trusted (20+): no cap; confirm unlimited or cost > $50.

## Exit Protocol

```
---HANDOFF---
- Target: {target} — Loop {n} of {n_total or "∞"} — Level {current_level}
- Outcome: {improved | plateau | ceiling | aborted | n-complete | level-up-triggered}
- Score movement: {axis} {before} → {after} (+{delta})
- Behavioral simulation: {PASS {wall_time} | FAIL | SKIPPED}
- Proposed rubric additions: {count} — written to .planning/rubrics/{target}-proposals.md
- Loop log: .planning/improvement-logs/{target}/loop-{n}.md
- Reversibility: amber -- each loop commits separately, revert individual loops with git revert
- Next recommended axis: {axis_name} (if not exiting)
- Level-up snapshot: .planning/rubrics/{target}-level-{n}-final.md (if level-up triggered)
---
```

© SethGammon · MIT · SethGammon/Citadel

Похожие скиллы

Все скиллы по теме «Тесты и QA» →

Сначала — improve от других авторов.

improve shadcn Скилл improve анализирует кодовую базу в режиме чтения и создаёт автономные пошаговые планы для других агентов. Помогает найти баги, долги архитектуры и проблемы безопасности без правки файлов. CX Codex +1 42 400установок improve owainlewis Скилл improve для Claude Code упрощает существующий код, сохраняя его поведение. Агент ищет дубли, мёртвый код, слабые имена и лишние абстракции. CX Codex +1 372установок improve Rudolf S. Скилл improve ищет модули с раздутыми интерфейсами и предлагает рефакторинги, которые превращают их в глубокие — тестируемые и удобные для навигации агентом. CX Codex +1 ★ 587звёзд репо evaluation-rubrics lyndonkl Скилл evaluation-rubrics помогает собрать рубрику с критериями, шкалой и описанием уровней, чтобы оценивать работу одинаково при повторных проверках. CX Codex +1 792установок skill-grader curiositech Скилл skill-grader для Claude Code оценивает Claude Agent Skills по 10 осям, выставляет оценки от A+ до F и предлагает улучшения. Для аудита одного скилла, сравнения нескольких или проверки библиотеки. CX Codex +1 147установок component-state-auditor ShuaiMXu Скилл component-state-auditor для Claude Code сравнивает задокументированные состояния компонентов с правилами из файла rubric.json. Он помогает выявить недостающие состояния в коде и дизайне перед релизом. CX Codex +1 ★ 529звёзд репо improve-codebase-architecture Matt Pocock Скилл improve-codebase-architecture для Claude Code ищет архитектурные узкие места в кодовой базе и показывает варианты углубления модулей в HTML-отчёте. Отчёт содержит материал для ревью перед рефакторингом. CX Codex +1 1 163 035установок improve-code-quality wondelai Скилл improve-code-quality для Claude Code и Codex ведёт проект от непротестированного прототипа к стабильному релизу. Пошаговый план фиксирует тесты, долг и архитектурные решения прямо в папке docs/. CX Codex +1 2 700установок improve-game OpusGameLabs Скилл improve-game аудитирует игру по тринадцати параметрам, находит слабые места и реализует исправления по убыванию эффекта. Запускается столько раз, сколько нужно. CX Codex +1 1 200установок

Из того же набора55

Весь набор →
research Скилл research собирает факты по техническому вопросу, оценивает надёжность источников и сохраняет структурированную сводку в Markdown. CX Codex +1 ★ 937звёзд репо learn Скилл learn собирает выводы завершённых кампаний или циклов evolve и встраивает их в вики проекта. Помогает сохранить рабочие подходы и решения для следующих сессий. CX Codex +1 ★ 937звёзд репо dashboard Скилл dashboard для Claude Code показывает состояние harness: кампании, сессии агентов, телеметрию и очереди. Он запускается по /dashboard, /do status или просьбе показать активность. CX Codex +1 ★ 937звёзд репо evolve Скилл evolve для Claude Code и Codex, который ведёт долгосрочное улучшение кода через формирование гипотез о причинах низких оценок, проверку их разведагентами и координированные атаки на слабые места. CX Codex +1 ★ 937звёзд репо daemon Скилл daemon запускает кампании Citadel в режиме непрерывной работы, цепляя сессии Claude Code друг за другом, пока не исчерпается бюджет или фаза не завершится. CX Codex +1 ★ 937звёзд репо setup Скилл setup для Claude Code и Codex автоматически настраивает проект на первый запуск: устанавливает хуки, определяет стек технологий, создаёт конфиг harness.json и показывает живую демонстрацию на вашем коде. CX Codex +1 ★ 937звёзд репо archon Скилл archon для Claude Code разбивает большие проекты на фазы, делегирует работу субагентам и сохраняет состояние между сеансами. CX Codex +1 ★ 937звёзд репо do Скилл do для Claude Code разбирает запрос и выбирает маршрут: прямую команду, скилл, оркестратор или план Operation Control. CX Codex +1 ★ 937звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой