ctx-refactor
Refactor code safely: test-first, one change at a time, preserve behavior. Use when the user says 'refactor this', 'clean this up', or wants structural improvement.
Best use case
ctx-refactor is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Refactor code safely: test-first, one change at a time, preserve behavior. Use when the user says 'refactor this', 'clean this up', or wants structural improvement.
Teams using ctx-refactor should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/ctx-refactor/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How ctx-refactor Compares
| Feature / Agent | ctx-refactor | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Refactor code safely: test-first, one change at a time, preserve behavior. Use when the user says 'refactor this', 'clean this up', or wants structural improvement.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
Refactor the specified code following strict safety rules. Refactoring changes structure, not outcomes. ## When to Use - User says "refactor this", "clean this up", "simplify this" - User wants to extract, rename, split, or reorganize code - User says "this is messy" or "can we improve this" ## When NOT to Use - User wants to add new behavior (that's a feature, not a refactor) - User wants a rename across the codebase (prefer `/gitnexus-refactoring` if GitNexus is available; otherwise use grep-based search to find all references before renaming) ## Rules Follow these in order. Do not skip steps. 1. **Write or verify tests first**: confirm existing behavior is captured before changing structure. 2. **Preserve all existing behavior**: refactoring changes structure, not outcomes. If a step would change observable behavior, stop and flag it as a separate task. 3. **Make one structural change at a time**: keep each step reviewable and revertible. 4. **Run tests after each step**: catch regressions immediately, not at the end. 5. **Check project conventions**: consult `.context/CONVENTIONS.md` to ensure the refactored code follows established patterns. ## Execution 1. Read `.context/CONVENTIONS.md` to load project patterns 2. Read the target code and its tests 3. If no tests exist, write them first (confirm with user) 4. Plan the refactoring steps: present to user before starting 5. Execute one step at a time, running tests between each 6. After all steps, run `make lint && make test` ## Output Format Before starting, present the plan: ``` ## Refactoring Plan: <target> 1. <step>: why 2. <step>: why ... Tests to verify: <list> ``` After each step, report: what changed, tests still passing.
Related Skills
ctx-verify
Verify before claiming completion. Use before saying work is done, tests pass, or builds succeed.
ctx-skill-creator
Create, improve, test, and deploy skills. Full skill lifecycle from intent to working skill file.
ctx-sanitize-permissions
Audit tool permissions for dangerous or overly broad entries. Use to ensure safe agent configuration.
ctx-recall
Browse session history. Use when referencing past discussions or finding context from previous work.
ctx-prompt
Apply, list, and manage saved prompt templates from .context/prompts/. Use when the user asks to apply, list, or create a reusable template like code-review or refactor.
ctx-journal-normalize
Normalize journal source markdown for clean rendering. Use after journal site shows rendering issues: fence nesting, metadata formatting, broken lists.
ctx-import-plans
Import plan files into project specs directory. Use to convert external plans into project-tracked specs.
ctx-compact
Archive completed tasks and trim context. Use when context files are growing large.
ctx-check-links
Audit docs for dead links. Use before releases, after restructuring docs, or when running a documentation audit.
ctx-add-task
Add a task. Use when follow-up work is identified or when breaking down complex work into subtasks.
ctx-add-learning
Record a learning. Use when discovering gotchas, bugs, or unexpected behavior that future sessions should know about.
ctx-add-decision
Record architectural decision. Use when a trade-off is resolved or a non-obvious design choice is made that future sessions need to know.