---

name: skill-improve description: This skill should be used when improving existing Claude Code skills. Triggers include "improve this skill", "skill feels shallow", "upgrade skill", or when self-evaluating skill quality. Codifies the self-eval → research → rewrite → validate pattern.

skill-improve

systematic improvement of Claude Code skills. transforms shallow, generic skills into deep, actionable expertise with decision trees, concrete values, and validated artifacts.

philosophy

"a skill is only as good as the decision it enables"

principle	application
primary sources	read actual source code, not summaries
decision trees	actionable if/then logic, not philosophy
concrete values	numbers, timings, constants from source
tool integration	connect to user's existing tools
validation required	both consult-deep AND artifact

when to use

use	skip
skill feels shallow or generic	skill is newly created (use create-skill)
self-evaluation scores < 7	minor typo/formatting fixes
"improve this skill" request	deleting a skill
periodic skill audits	skill has recent validation

workflow

1. self-evaluate

rate the skill 1-10 on these criteria:

criterion	question	weight
decision trees	does it have if/then logic for common scenarios?	high
concrete values	does it cite specific numbers, timings, constants?	high
primary sources	was it built from actual source code/docs?	high
tool integration	does it connect to user's existing tools?	medium
anti-patterns	does it list what NOT to do with fixes?	medium
references depth	are references substantive, not stubs?	medium

scoring:

• 8-10: skill is mature, periodic review only
• 5-7: needs improvement, run full workflow
• 1-4: needs rewrite, prioritize immediately

2. identify gaps

use this decision tree:

Is the skill shallow?
├── No decision trees? → Add if/then scenarios for common use cases
├── No concrete values? → Research primary sources for numbers
├── Generic patterns? → Integrate with user's specific tools
├── Missing anti-patterns? → Document common mistakes + fixes
└── Stub references? → Expand with substantive content

3. research primary sources

use Ref MCP to ground improvements:

# search for library/framework docs
mcp__Ref__ref_search_documentation "library_name patterns 2025"

# read specific doc pages
mcp__Ref__ref_read_url "https://docs.example.com/guide"

# for domain skills, read actual source code
# example: sonner toast library
WebFetch "https://raw.githubusercontent.com/emilkowalski/sonner/main/src/index.tsx"

what to extract:

• default values and constants
• timing/duration values
• threshold values
• configuration patterns
• internal naming conventions

4. rewrite with improvements

structure the improved skill:

# skill-name

one-line description of what this enables.

## philosophy
> "memorable quote that captures the essence"

| principle | application |
|-----------|-------------|

## when to use
| use | skip |
|-----|------|

## decision tree (THE CORE)

Should I [action]? ├── [condition 1]? → [specific action with value] ├── [condition 2]? → [different action] └── [default]? → [fallback]

## concrete values (FROM SOURCE)
| constant | value | source |
|----------|-------|--------|

## tool integration
how this connects to user's existing setup.

## anti-patterns
| pattern | problem | fix |
|---------|---------|-----|

## references
links to references/*.md for deep dives

5. validate: consult-deep

run thorough AI review via Codex CLI:

cat <<'EOF' | codex exec --model gpt-5.2-max
Skill depth review.

Skill: [skill_name]
Content: [paste SKILL.md content]

Validate:
1. Decision trees present and actionable?
2. Concrete values from primary sources?
3. Tool integration with user's setup?
4. Anti-patterns documented?
5. Would domain expert recognize as informed?

Output JSON: {
  pass: bool,
  depth_score: 1-10,
  issues: [],
  missing_sources: [],
  confidence: 1-10
}
EOF

pass criteria: depth_score >= 8, confidence >= 8

6. validate: create artifact

every improved skill must produce a validating artifact:

skill type	artifact
domain (emil-kowalski)	create component using the skill
tool (slack)	run workflow using skill patterns
workflow (loop)	execute one iteration on real issue
meta (skill-improve)	improve another skill using it

7. validate: consult-light on artifact

quick review of the created artifact:

cat <<'EOF' | cursor-agent -p --model gemini-3-pro
Artifact validation.

Skill: [skill_name]
Artifact: [description of what was created]
Skill principles applied: [list]

Questions:
1. Does artifact demonstrate skill mastery?
2. Are skill patterns correctly applied?
3. Would this artifact convince a skeptic?

Output JSON: {pass: bool, score: 1-10, issues: [], confidence: 1-10}
EOF

pass criteria: score >= 8, confidence >= 8

quality checklist

before marking improvement complete:

• decision tree covers 80% of common scenarios
• concrete values cite source (file, line, or doc URL)
• references/*.md are substantive (>50 lines each)
• anti-patterns include specific fixes
• consult-deep returned depth_score >= 8
• artifact created and validated
• consult-light returned score >= 8

references

• references/evaluation-rubric.md - detailed scoring criteria
• references/research-patterns.md - how to find primary sources
• references/artifact-examples.md - validation artifacts by skill type

anti-patterns

pattern	problem	fix
web-scrape only	summaries miss implementation details	read actual source code
philosophy without action	"be thoughtful" isn't actionable	add if/then decision tree
generic values	"200-300ms" without source	cite exact constant from code
skip validation	"looks good" isn't validation	require both consult + artifact
improvement without artifact	no proof it works	create something using the skill