skills.rest
jmrplens
jmrplensCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

modularize-go-package

Migrates monolithic Go packages into domain-specific sub-packages with verified compilation and tests.

37|4|Updated Apr 11, 2026
Search Tags:#refactoring#go#code organization#monolith#modularization#golangci-lint#package migration
One-click install
npx skills add https://github.com/jmrplens/gitlab-mcp-server --skill modularize-go-package-jmrplens
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: modularize-go-package
Source: https://github.com/jmrplens/gitlab-mcp-server/tree/main/.github/skills/modularize-go-package
Command: npx skills add https://github.com/jmrplens/gitlab-mcp-server --skill modularize-go-package-jmrplens

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Large Go codebases accumulate monolithic packages with dozens of files that are hard to navigate, test, and maintain. This Skill guides an AI through a safe, incremental refactoring that splits a monolithic package into domain-aligned sub-packages without ever breaking the build or test suite. ## Core Features & Use Cases - Atomic migration batches: Moves one domain at a time into its own sub-package, verifying go build and go test after every batch so the project never enters a broken state. - Shared utilities extraction: Pulls common helpers (errors, pagination, logging, markdown formatting) into a dedicated utilities package with temporary forwarding stubs to avoid breaking unmigrated code. - Symbol renaming and catalog wiring: Renames types and handlers to drop redundant domain prefixes, creates action_specs.go files, and wires each domain into the catalog aggregation path. - Use Case: Given a 100-file internal/tools package in a GitLab MCP server, extract the branches, commits, and issues domains into their own sub-packages while keeping every intermediate commit green. ## Quick Start Ask the AI to modularize the internal/tools package by extracting the branches, commits, and issues domains into sub-packages using this skill.

Frequently Asked Questions about modularize-go-package

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I split a large Go package into sub-packages without breaking the build?▼

Migrate one domain at a time in atomic batches: move the handler and test files, update imports and symbol names, then run go build and go test before starting the next domain. Temporary forwarding stubs keep unmigrated code compiling during the transition.

How to extract shared utilities when modularizing Go code?▼

Create a dedicated utilities package and extract shared code in dependency order: pure types first, then types depending on external libraries, then functions, then complex utilities. Export all symbols used by domain handlers and leave forwarding stubs in the original package until migration completes.

What causes undefined symbol errors after moving Go files to a new package?▼

Unexported symbols like wrapErr are not visible across package boundaries. Fix this by exporting them in the shared utilities package (WrapErr) and updating call sites to use the qualified name such as toolutil.WrapErr.

How do I avoid circular imports when refactoring Go packages?▼

Circular imports happen when domain sub-packages import the parent package that imports them back. Break the cycle by extracting all shared code into a separate utilities package that has no dependencies on any domain sub-package.

When should a multi-file Go domain become multiple sub-packages?▼

Split into multiple sub-packages when files map to distinct API services, such as merge request notes, discussions, and approvals each using different client-go services. Keep files in one package when they share the same API domain, like the packages domain with its composite and stream files.

Related Skills

Explore More Software Engineering Skills→
vlad-ryzhkovvlad-ryzhkov
25

repo-scout

Audit Go backend repositories for API endpoints, infrastructure, and test coverage.

Community
Intermediate
pohlai88pohlai88

eslint-enterprise-monorepo

Configure scalable ESLint rules for pnpm/Turborepo monorepos with typed linting and CI boundaries enforcement.

Community
Advanced
agentmattersagentmatters
3

laravel-verification

Run environment checks, linting, static analysis, tests, and security scans for Laravel projects.

Official
Advanced
crgarcia12crgarcia12

rewrite-planner

Plan incremental component rewrites using the strangler fig pattern.

Community
Advanced