Go Package Refactoring Tool skill for Claude and Codex
A concrete plan to untangle a Go package: the import cycles and coupling found with file references, the new package boundaries, the order to move code so the…
Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.
Download the skill (.zip) · View SKILL.md
When it is used
Use when a Go package has import cycles, a god struct, global state, or too many exports and needs a step-by-step restructure plan that keeps the build green. Do not use for scaffolding a new package, or line-level cleanups like renaming variables inside one file. Related topics: coding, package.
What it will ask you for
- Package path (free text, e.g. "github.com/acme/app/internal/service")
- Package layout and imports (longer free text)
- Primary goal (choose one: Resolve circular dependencies, Reduce coupling, Improve testability, Optimize build time)
- Patterns to remove (choose any: Import cycles, Large single files, Global state usage, Excessive exports, God structs, Init functions with side effects)
- Target Go version (free text, e.g. "1.22")
- Constraints (longer free text)
- Maximum files per package (number from 1 to 20)
How it works
- Build the import graph from the supplied layout and list every cycle and over-coupled package with the files and identifiers involved.
- Define the new package boundaries by what changes together and what callers need, named for what they provide, within the files-per-package limit.
- Resolve each cycle by moving the shared type to its owner or by introducing a consumer-side interface, and replace global state with constructor parameters.
- Sequence the moves so go build and go test pass after every step, using forwarding aliases where exported names must survive.
- Write the new interfaces and changed signatures as Go code and flag any step that touches an API the constraints protect.
What you get
A markdown plan with three sections: Problems found (with file references), Migration steps (numbered, each leaving the build green), and Code (new interfaces and changed signatures in Go blocks).
What it watches out for
- Creating a util or common package to break a cycle, which becomes a new dumping ground that everything imports.
- Defining interfaces on the producer side with every method, when Go idiom wants small interfaces declared where they are consumed.
- Moving everything in one commit, so a single compile error blocks the whole refactor instead of one step.
How to install
Claude.ai and the Claude desktop app
- Download the skill .zip.
- Open Settings, then Capabilities, and find Skills.
- Choose Upload skill and select the .zip.
- Ask Claude for help with the task. It loads the skill when your request matches.
Claude Code
- Download the skill .zip.
- Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
- Start a new session. Claude Code loads the skill when your request matches.
Codex
- Download the skill .zip.
- Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
- Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.
Cursor
- Download the Cursor rule (.mdc).
- Save it in .cursor/rules/ inside your project.
- Cursor's agent applies the rule when your request matches its description.
AGENTS.md (Codex, Cursor, and other coding agents)
- Copy the AGENTS.md section.
- Paste it into AGENTS.md at the root of your repository, creating the file if needed.
- Coding agents that read AGENTS.md follow it when your request fits.