skill improve
- Repo stars 19,707
- Author repo Claude-Code-Game-Studios
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @Donchitos · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Read the skill name from the first argument. If missing, output usage and stop: Verify `.claude/skills/[name]/SKILL.md` exists. If not, stop with: "Skill '[name]' not found."
Run `/skill-test static [name]` and record the baseline score: Count of FAILs Count of WARNs Which specific checks failed (Check 1–7) Display to the user:
Look up the skill's `category:` field in `CCGS Skill Testing Framework/catalog.yaml`. If no `category:` field is found, display: "Category: not yet assigned — skipping category checks." and skip to Phase 3. If category is found, run `/skill-test category [name]` and record the category baseline:
Read the full skill file at `.claude/skills/[name]/SKILL.md`. For each failing or warning static check, identify the exact gap: Check 1 fail → which frontmatter field is missing Check 2 fail → how many phases found vs. minimum required Check 3 fail → no verdict keywords anywhere in the skill body
Write a targeted fix for each failure and warning. Show the proposed changes as clearly marked before/after blocks. Only change what is failing — do not rewrite sections that are passing. Ask: "May I write this improved version to `.claude/skills/[name]/SKILL.md`?" If the user says no, stop here.
Record the current content of the skill file (for revert if needed). Write the improved skill to `.claude/skills/[name]/SKILL.md`. Re-run `/skill-test static [name]` and record the new static score. If a category was assigned, also re-run `/skill-test category [name]` and record the new category score. Display the comparison:
Count the combined failure total: static FAILs + category FAILs + static WARNs + category WARNs. If combined score improved (combined failure count is lower than baseline): Report: "Score improved. Changes kept." Show a summary of what was fixed in each dimension. If combined score is the same or worse:
Run `/skill-test static all` to find the next skill with failures. Run `/skill-improve [next-name]` to continue the loop on another skill. Run `/skill-test audit` to see overall coverage progress.
# Skill Improve
Runs an improvement loop on a single skill:
test → fix → retest → keep or revert.
---
## Phase 1: Parse Argument
Read the skill name from the first argument. If missing, output usage and stop:
```
Usage: /skill-improve [skill-name]
Example: /skill-improve tech-debt
```
Verify `.claude/skills/[name]/SKILL.md` exists. If not, stop with:
"Skill '[name]' not found."
---
## Phase 2: Baseline Test
Run `/skill-test static [name]` and record the baseline score:
- Count of FAILs
- Count of WARNs
- Which specific checks failed (Check 1–7)
Display to the user:
```
Static baseline: [N] failures, [M] warnings
Failing: Check 4 (no ask-before-write), Check 5 (no handoff)
```
If baseline is 0 FAILs and 0 WARNs, note it and proceed to Phase 2b.
### Phase 2b: Category Baseline
Look up the skill's `category:` field in `CCGS Skill Testing Framework/catalog.yaml`.
If no `category:` field is found, display:
"Category: not yet assigned — skipping category checks."
and skip to Phase 3.
If category is found, run `/skill-test category [name]` and record the category baseline:
- Count of FAILs
- Count of WARNs
- Which specific category rubric metrics failed
Display to the user:
```
Category baseline: [N] failures, [M] warnings ([category] rubric)
```
If BOTH static and category baselines are 0 FAILs and 0 WARNs, stop:
"This skill already passes all static and category checks. No improvements needed."
---
## Phase 3: Diagnose
Read the full skill file at `.claude/skills/[name]/SKILL.md`.
For each failing or warning **static** check, identify the exact gap:
- **Check 1 fail** → which frontmatter field is missing
- **Check 2 fail** → how many phases found vs. minimum required
- **Check 3 fail** → no verdict keywords anywhere in the skill body
- **Check 4 fail** → Write or Edit in allowed-tools but no ask-before-write language
- **Check 5 warn** → no follow-up or next-step section at the end
- **Check 6 warn** → `context: fork` set but fewer than 5 phases found
- **Check 7 warn** → argument-hint is empty or doesn't match documented modes
For each failing or warning **category** check (if category was assigned in Phase 2b),
identify the exact gap in the skill's text. For example:
- If G2 fails (gate mode, full directors not spawned): skill body never references all 4
PHASE-GATE director prompts
- If A2 fails (authoring, no per-section May-I-write): skill asks once at the end, not
before each section write
- If T3 fails (team, BLOCKED not surfaced): skill doesn't halt dependent work on blocked agent
Show the full combined diagnosis to the user before proposing any changes.
---
## Phase 4: Propose Fix
Write a targeted fix for each failure and warning. Show the proposed changes
as clearly marked before/after blocks. Only change what is failing — do not
rewrite sections that are passing.
Ask: "May I write this improved version to `.claude/skills/[name]/SKILL.md`?"
If the user says no, stop here.
---
## Phase 5: Write and Retest
Record the current content of the skill file (for revert if needed).
Write the improved skill to `.claude/skills/[name]/SKILL.md`.
Re-run `/skill-test static [name]` and record the new static score.
If a category was assigned, also re-run `/skill-test category [name]` and record the new category score.
Display the comparison:
```
Static: Before [N] failures, [M] warnings → After [N'] failures, [M'] warnings
Category: Before [N] failures, [M] warnings → After [N'] failures, [M'] warnings (if applicable)
Combined change: improved / no change / worse
```
---
## Phase 6: Verdict
Count the combined failure total: static FAILs + category FAILs + static WARNs + category WARNs.
**If combined score improved (combined failure count is lower than baseline):**
Report: "Score improved. Changes kept."
Show a summary of what was fixed in each dimension.
**If combined score is the same or worse:**
Report: "Combined score did not improve."
Show what changed and why it may not have helped.
Ask: "May I revert `.claude/skills/[name]/SKILL.md` using git checkout?"
If yes: run `git checkout -- .claude/skills/[name]/SKILL.md`
---
## Phase 7: Next Steps
- Run `/skill-test static all` to find the next skill with failures.
- Run `/skill-improve [next-name]` to continue the loop on another skill.
- Run `/skill-test audit` to see overall coverage progress.
Listed in source order.
sections -> Phase 1: Parse Argument → Phase 2: Baseline Test → Phase 2b: Category Baseline → Phase 3: Diagnose → Phase 4: Propose Fix → Phase 5: Write and Retest
terms -> static · Check 1 fail · Check 2 fail · Check 3 fail · Check 4 fail · Check 5 warn · Check 6 warn · Check 7 warn
files/cmd -> .claude/skills/[name]/SKILL.md · /skill-test static [name] · category: · CCGS Skill Testing Framework/catalog.yaml · /skill-test category [name] · context: fork · git checkout -- .claude/skills/[name]/SKILL.md · /skill-test static all
body sha256 -> 59acf2a29994
Phase 1: Parse Argument
Read the skill name from the first argument. If missing, output usage and stop: Verify
.claude/skills/[name]/SKILL.mdexists. If not, stop with: "Skill '[name]' not found."Phase 2: Baseline Test
Run
/skill-test static [name]and record the baseline score: Count of FAILs Count of WARNs Which specific checks failed (Check 1–7) Display to the user:Phase 2b: Category Baseline
Look up the skill's
category:field inCCGS Skill Testing Framework/catalog.yaml. If nocategory:field is found, display: "Category: not yet assigned — skipping category checks." and skip to Phase 3. If category is found, run/skill-test category [name]and record the category baseline:Phase 3: Diagnose
Read the full skill file at
.claude/skills/[name]/SKILL.md. For each failing or warning static check, identify the exact gap: Check 1 fail → which frontmatter field is missing Check 2 fail → how many phases found vs. minimum required Check 3 fail → no verdict keywords anywhere in the skill bodyPhase 4: Propose Fix
Write a targeted fix for each failure and warning. Show the proposed changes as clearly marked before/after blocks. Only change what is failing — do not rewrite sections that are passing. Ask: "May I write this improved version to
.claude/skills/[name]/SKILL.md?" If the user says no, stop here.