improve · owainlewis — Claude Code skill: refactor code without behavior changes
Makes existing code easier to read while keeping what it does intact. Useful for stripping duplication, dead code and needless abstractions.
npx skills add owainlewis/blueprint --skill improve -a claude-codeWhat improve does
The improve skill picks its target from your request, the current diff, or recently changed files. It reads the code, the tests and the surrounding context, then states which behavior must stay the same. If that behavior has no tests, it adds focused coverage first, runs it against the untouched code, and commits that test-only change on its own. Refactoring starts after that.
Edits come as deletion, deduplication, renaming, simplification, extraction or inlining. Public interfaces, data shapes, errors and anything user-visible stay put unless you explicitly ask otherwise. At the end the skill runs the tests and checks covering the affected behavior and reports what got simpler, what was preserved, and what proves it.
Boundaries are tight: no new product scope, no unrelated cleanup picked up along the way. A few clear edits beat a broad rewrite. When a behavior can't be exercised by automated tests, the skill says so and names another form of evidence — worth checking whether that part of your codebase has tests at all.
What it helps with
- remove duplication spread across several functions
- clear dead code before a release
- rename variables and functions so they read on the first pass
- drop an abstraction layer that costs more than it helps
- add tests for behavior you are about to refactor
Example prompts for the agent
- improve: simplify
src/parser.ts, keep behavior unchanged - improve: deduplicate the reporting module, tests must stay green
- improve: go through the current diff and remove dead code
How to install improve
1Skills CLI (Vercel)
npx skills add owainlewis/blueprint --skill improve -a claude-code2Manually: put the files in place
~/.claude/skills/improve/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/improve/
1Skills CLI (Vercel)
npx skills add owainlewis/blueprint --skill improve -a codex2Manually: put the files in place
.agents/skills/improve/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add owainlewis/blueprint --skill improve -a cursor2Manually: put the files in place
.cursor/skills/improve/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install owainlewis/blueprint improve2Manually: put the files in place
.github/skills/improve/SKILL.md1Skills CLI (Vercel)
npx skills add owainlewis/blueprint --skill improve -a gemini-cli2Platform CLI
gemini skills install https://github.com/owainlewis/blueprint --path skills/improveManually: put the files in place
.devin/skills/improve/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add owainlewis/blueprint --skill improve -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about improve
How do I install improve in Claude?
Run npx skills add owainlewis/blueprint --skill improve -a claude-code. The skill lands in ~/.claude/skills/improve/SKILL.md.
What does improve do?
It makes existing code easier to understand without changing behavior: simplifying structure, removing duplication and dead code, fixing names and unnecessary abstractions.
Does improve change public interfaces?
No, unless you explicitly ask for it. Public interfaces, data shapes, errors and user-visible behavior are preserved.
Source text
SKILL.md · MIT
--- name: improve description: "Makes existing code easier to understand without changing behavior. Use to simplify structure, remove duplication or dead code, improve names, or remove unnecessary abstractions." user-invocable: true argument-hint: "[code, files, diff, branch, or improvement focus]" disable-model-invocation: true --- # Improve Make code easier to understand without changing what it does. Reduce the layers a reader must trace and the hidden state they must remember. ## Process 1. Identify the target from the request, current diff, or recently changed code. 2. Read the target, its tests, and relevant surrounding code. State the behavior that must not change. 3. If that behavior lacks tests, add focused coverage and run it against the unchanged code. Commit the passing test-only change before refactoring. If automated tests cannot exercise the behavior, explain why and give other evidence. 4. Find unnecessary complexity, duplication, dead code, weak names, awkward boundaries, and abstractions that cost more than they help. 5. Make focused improvements by deleting, deduplicating, renaming, simplifying, extracting, or inlining. 6. Preserve public interfaces, data shapes, errors, and user-visible behavior unless the user explicitly asks to change them. 7. Run tests and checks that cover behavior the refactor can affect. Report what improved, what behavior was preserved, and the evidence. ## Return State what became simpler, what behavior stayed the same, and which checks prove it. Name any behavior that remains unverified. ## Boundaries - Do not add product scope or absorb unrelated cleanup. - Prefer a few clear edits over a broad rewrite. - Preserve behavior even when a redesign would be easier.
© owainlewis · MIT · owainlewis/blueprint
Similar skills
Everything for Code review and refactoring →improve by other authors comes first.
