New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Refactor

by softspark in softspark/ai-toolkit

Refactors code for quality and maintainability. An agent skill from softspark/ai-toolkit.

Apache-2.0Auto-check: notesDevelopment

Install Refactor

skills CLI
$ npx skills add softspark/ai-toolkit --skill refactor -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install softspark/ai-toolkit refactor --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/softspark/ai-toolkit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/app/skills/refactor .claude/skills/refactor && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
refactor
GitHub stars
179
Token cost
~1.5k tokens
SKILL.md length
667 words
Files
2 (incl. scripts)
Skills in repo
112
Repo updated
First seen
Licence
Apache-2.0

At a glance

Refactors code for quality and maintainability. An agent skill from softspark/ai-toolkit.

  • Works in 4 steps: Analyzes target code → Identifies refactoring opportunities → Plans refactoring steps → …
  • Tasks that involve Refactoring
  • SKILL.md covers Usage, What This Command Does, Refactoring Patterns and Safety Rules, plus 11 more sections
  • Runs Python scripts from its folder; calls git and python3

What it does

Refactor is an agent skill from softspark/ai-toolkit. Refactors code for quality and maintainability. Triggers: refactor, clean up, restructure, improve code, modernize.

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/refactor-scan.py`).

It sits in Development, covering Refactoring. The repository describes itself as: Professional-grade AI coding toolkit: 94 skills, 44 agents, multi-platform (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Antigravity, Codex CLI… The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve Refactoring

Example prompts

  • “Use the refactor skill to refactor code for quality and maintainability. An agent skill from softspark/ai-toolkit”
  • “/refactor”

Requirements

  • Python 3
  • Pre-approved tools (allowed-tools): Read, Edit, Grep, Glob, Bash

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Analyzes target code
  2. Identifies refactoring opportunities
  3. Plans refactoring steps
  4. Executes with user approval

What it can do on your machine

Read from SKILL.md and the folder at commit d64db2b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Edit
    • Grep
    • Glob
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • git
    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Refactor loads about 1.5k tokens when it runs. Until then it costs about 31 tokens; SKILL.md has 667 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~31
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Edit, Grep, Glob, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from softspark/ai-toolkit at commit d64db2b, republished under its Apache-2.0 licence (© softspark). 667 words, ~1,544 tokens.

Download SKILL.mdSave it as .claude/skills/refactor/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
refactor
description
Refactors code for quality and maintainability. Triggers: refactor, clean up, restructure, improve code, modernize.
allowed-tools
Read, Edit, Grep, Glob, Bash
user-invocable
true
effort
high
argument-hint
[target and goal]
agent
code-reviewer
context
fork

Refactor Code

$ARGUMENTS

Plan and execute code refactoring.

Usage

/refactor [target] [--pattern=<pattern>]

What This Command Does

  1. Analyzes target code
  2. Identifies refactoring opportunities
  3. Plans refactoring steps
  4. Executes with user approval

Refactoring Patterns

PatternDescription
extract-functionExtract code block to function
extract-componentExtract UI component
renameRename symbol across codebase
moveMove code to better location
inlineInline unnecessary abstraction
simplifySimplify complex logic

Safety Rules

  • Run tests before refactoring
  • Make atomic commits
  • Preserve behavior (no feature changes)
  • Run tests after each step
  • Don't mix refactoring with features

Output Format

markdown
## Refactoring Plan: [Target]

### Current State
- **Location**: [file:line]
- **Issues**: [what's wrong]

### Proposed Changes
1. [Change 1]
2. [Change 2]

### Impact Analysis
- **Files affected**: [count]
- **Risk level**: [Low/Medium/High]

### Test Coverage
- [x] Unit tests exist
- [ ] Integration tests needed

### Rollback

git revert [commit]

Approval Required

Before executing:

  • Plan reviewed
  • Tests passing
  • Backup created

Common Rationalizations

ExcuseWhy It's Wrong
"It works, don't touch it"Working code that's hard to maintain slows every future change
"We'll refactor it later"Later never comes — refactor when the pain is fresh and context is loaded
"It's too risky to change"That's exactly why it needs refactoring — risk compounds with complexity
"Just one more hack won't hurt"Each hack makes the next one easier to justify — break the cycle now
"We need to rewrite from scratch"Incremental refactoring is safer and delivers value continuously

READ BEFORE WRITE

This command analyzes and plans first. Execution requires explicit approval.

MANDATORY: Documentation Update

After refactoring, update documentation:

Required Updates
Change TypeUpdate
API changesAPI documentation
Architecturearchitecture note if significant
PatternsBest practices docs
Breaking changesMigration guide
Post-Refactoring Checklist
  • Tests still pass
  • No behavior changes
  • Documentation updated if interfaces changed
  • Code comments updated

Automated Smell Detection

Run the bundled script to find refactoring opportunities:

bash
python3 ${CLAUDE_SKILL_DIR}/scripts/refactor-scan.py src/

Parallel Refactoring (complex cases)

If the scan reports >5 smells across multiple files, use Agent Teams:

Create an agent team for refactoring:
- Teammate 1 (code-reviewer): "Plan the refactoring strategy for [identified smells]. Document what to change and why." Use Opus. READ-ONLY.
- Teammate 2 (backend-specialist): "Implement the refactoring changes identified by the reviewer." Use Opus.
Teammate 1 completes first, then Teammate 2 acts on the plan.
  • Need a safe refactor plan? → /refactor-plan for incremental steps as GitHub RFC
  • Want to validate architecture? → /analyze for code quality metrics
  • Need tests before refactoring? → /tdd to build safety net first
  • Architecture decision needed? → /council for multi-perspective evaluation

Rules

  • MUST run the full test suite before starting — a green baseline is the only way to tell the refactor did not break anything
  • MUST preserve behavior end-to-end; if behavior must change, stop and ask — "while we're here" changes are how refactors introduce bugs
  • NEVER mix refactoring with feature changes in the same commit — they fail review and rollback differently
  • NEVER refactor untested code without adding tests first — the refactor has nothing to assert against
  • CRITICAL: commits stay small and individually reversible. A 2000-line refactor commit cannot be code-reviewed and cannot be bisected.
  • MANDATORY: dead-code cleanup is part of the refactor per Constitution Art. VI.1 — orphaned references left behind from a refactor are a quality regression, not "later work"
Show full SKILL.md (235 more words)Show less

Gotchas

  • "Behavior-preserving" refactors still change observable things: timing, memory allocation, error message text, log line format. Downstream consumers may rely on these — scan for log parsers or monitoring rules before changing prose in exceptions.
  • IDE rename refactors miss dynamic references (string-keyed dicts, reflection, getattr, dynamic imports). After a rename, grep for the old name in strings and comments — the IDE will not.
  • Git history diffing is confused by combined move + content changes. Split moves into their own commit (git mv + tiny commit) so later reviewers can use git log --follow.
  • Preserving backward compatibility is a spectrum. "Keep the old function as a thin wrapper" sounds safe but often defers the cleanup forever — prefer deprecate-with-warning followed by a scheduled removal.
  • Refactor-to-DRY abstractions made from 2 use cases often need to be torn down when the 3rd use case arrives (Rule of Three). Resist abstracting until the third repetition makes the shape obvious.
  • Test suites that rely on mocks frequently pass during refactors that silently break real behavior (the mock reflects the old shape). Run integration tests, not just unit, before marking done.

When NOT to Use

  • For planning a refactor (no execution) — use /refactor-plan
  • For architectural audit of shallow modules — use /architecture-audit
  • For fixing a specific bug — use /fix or /debug
  • For adding a feature — use /plan then the relevant language skill
  • When tests do not exist or are red — write tests first (/tdd) before refactoring

© softspark, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in app/skills/refactor of softspark/ai-toolkit.

  • SKILL.md
  • scripts/refactor-scan.py

Open the folder on GitHubat commit d64db2b

Compare with similar skills

Refactor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Refactor compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Refactor this skillsoftspark/ai-toolkit179—~1.5kAutomated safety check: NotesApache-2.0
Guidelinesakash-network/node1.1k22 repos~577Automated safety check: PassMIT
Component Refactoringlangflow-ai/langflow156k—~3.5kAutomated safety check: PassMIT
Migrate Core Code to Submodulestinyhumansai/openhuman41k—~2.6kAutomated safety check: PassGPL-3.0
ast-grep Structural Searchcode-yeongyu/oh-my-openagent70k—~3.3kAutomated safety check: PassMIT
Systematic Code Refactoringluongnv89/claude-howto42k—~3kAutomated safety check: PassMIT

Similar skills

  • Guidelines

    akash-network/node

    Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.

    1.1k GitHub starsUsed in 22 repos~577 tokens
    DevelopmentAuto-check passed

  • Component Refactoring

    langflow-ai/langflow

    Refactor high-complexity React components in Langflow frontend.

    156k GitHub stars~3.5k tokensUpdated today
    DevelopmentAuto-check passed

  • Migrate Core Code to Submodules

    tinyhumansai/openhuman

    Plans and carries out moving non-host-specific code and its tests from the OpenHuman core into vendored tiny submodule libraries, then releases the submodule and re-pins the host.

    41k GitHub stars~2.6k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • ast-grep Structural Search

    code-yeongyu/oh-my-openagent

    Searches and rewrites code by syntax-tree shape across 25 languages with ast-grep, for codemods, structural queries and YAML lint rules, using a Python wrapper script.

    70k GitHub stars~3.3k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Systematic Code Refactoring

    luongnv89/claude-howto

    Guides refactoring in phases based on Martin Fowler's method: research, test coverage check, planning and small tested steps, with your approval at each phase.

    42k GitHub stars~3k tokensUpdated 7 days ago
    DevelopmentAuto-check passed

  • Codex

    skills-directory/skill-codex

    A skill your agent uses when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing

    1.5k GitHub starsUsed in 3 repos~1.8k tokens
    DevelopmentAuto-check passed

More from softspark/ai-toolkit

All 112 skills in this repo

  • Prepare Test Env

    softspark/ai-toolkit

    Prepare or verify a project QA environment with source identity, readiness, browser access, evidence paths and owned cleanup.

    179 GitHub stars~1.8k tokensUpdated yesterday
    Auto-check: notes

  • A11y Validate

    softspark/ai-toolkit

    Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. An agent skill from softspark/ai-toolkit.

    179 GitHub stars~3.8k tokensUpdated yesterday
    Auto-check: notes

  • Analyze

    softspark/ai-toolkit

    Analyzes code quality, complexity, patterns across codebase.

    179 GitHub stars~1k tokensUpdated yesterday
    Auto-check passed

  • Autonomous Dev

    softspark/ai-toolkit

    Drives a brief, specification, issue or existing PR through implementation, review, tests and QA to a ready PR.

    179 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check: notes

  • Brand Voice

    softspark/ai-toolkit

    Direct technical voice for docs, README, user-facing text. An agent skill from softspark/ai-toolkit.

    179 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed

  • CI

    softspark/ai-toolkit

    Detect/generate/debug CI pipeline config (GitHub Actions, GitLab CI).

    179 GitHub stars~1.1k tokensUpdated yesterday
    Auto-check: notes

Categories

Questions about Refactor

What does Refactor do?

Refactors code for quality and maintainability. An agent skill from softspark/ai-toolkit. Refactor is an agent skill from softspark/ai-toolkit. Refactors code for quality and maintainability.

When should I use Refactor?

Refactor fits situations like: tasks that involve Refactoring.

How do I install Refactor in Claude Code?

Run `npx skills add softspark/ai-toolkit --skill refactor -a claude-code`. Or copy the skill folder (app/skills/refactor in softspark/ai-toolkit) into .claude/skills/refactor in your project. Claude Code loads it when a task matches its description.

How do I install Refactor in Codex?

Run `npx skills add softspark/ai-toolkit --skill refactor -a codex`. Or copy the skill folder (app/skills/refactor in softspark/ai-toolkit) into .agents/skills/refactor in your project. Codex loads it when a task matches its description.

Can I use Refactor in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add softspark/ai-toolkit --skill refactor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/refactor, .gemini/skills/refactor, .github/skills/refactor and .opencode/skills/refactor in your project.

What does Refactor need to run?

Going by SKILL.md and its folder, Refactor needs Python for the scripts in its folder and the command-line tools its instructions call (git and python3). Our summary lists: Python 3. Its frontmatter pre-approves these tools: Read, Edit, Grep, Glob, Bash.

Does Refactor access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Refactor safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Refactor use?

Refactor is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Refactor use?

About 1.5k tokens (SKILL.md is roughly 6.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Refactor?

Skills that share tags, products or a category with Refactor: Guidelines (akash-network/node, 1.1k stars), Component Refactoring (langflow-ai/langflow, 156k stars), Migrate Core Code to Submodules (tinyhumansai/openhuman, 41k stars) and ast-grep Structural Search (code-yeongyu/oh-my-openagent, 70k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Refactor?

softspark (a GitHub user) maintains it in softspark/ai-toolkit, which has 179 GitHub stars. The repository holds 112 skills in this directory. The repository was last updated on October 7, 2026.

Source: softspark/ai-toolkit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.