Claude-skill-registry internal-package-building

Guides adding and structuring internal Go packages: when to create a new package, import paths, cmd vs internal boundaries, and domain layout. Use when creating or refactoring code under internal/, adding a new domain, or when the user asks about internal package structure.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/internal-package-building" ~/.claude/skills/majiayu000-claude-skill-registry-internal-package-building && rm -rf "$T"

manifest: skills/data/internal-package-building/SKILL.md

Internal Package Building Skill

Use this skill when creating or refactoring internal Go packages.

When to create a new package

New domain → new directory under
```
internal/
```
(e.g. new feature area or bounded context).
Existing domain → add or edit files in the existing package; do not split without a clear boundary.
Shared cross-cutting concern (DB, config, models) → use or extend existing shared packages (
```
internal/db
```
,
```
internal/models
```
,
```
internal/env
```
) rather than creating a new one unless the concern is clearly separate.

Layout

One package per directory; package name = directory name (e.g.
```
internal/candidate_tree
```
→
```
package candidate_tree
```
).
Entrypoints live only in cmd/ (e.g.
```
cmd/api
```
,
```
cmd/evaluator
```
,
```
cmd/importer
```
). All shared logic lives in internal/.
internal/ must not import cmd/; cmd packages wire and call internal packages.

Imports

Import internal packages by module path:
```
tarkov-build-optimiser/internal/<pkg>
```

Example:

import "tarkov-build-optimiser/internal/models"

Existing internal packages (use, don’t duplicate)

Package	Role
`internal/db`	Database connections and pool
`internal/models`	Data types and SQL access (UpsertX, GetXById, etc.)
`internal/env`	Environment/config
`internal/helpers`	Shared pure helpers (e.g. maths)
`internal/cache`	Caching utilities
`internal/candidate_tree`	Build candidate tree logic
`internal/evaluator`	Build evaluation
`internal/importers`	Data import from external sources
`internal/router`	HTTP routing and handlers
`internal/tarkovdev`	tarkov.dev API client

Checklist for a new internal package

Create
```
internal/<name>/
```
with at least one
```
.go
```
file; package name =
```
<name>
```
.
Add only code that belongs to that domain; put shared DB/config in
```
internal/db
```
or
```
internal/env
```
.
Import other internal packages via
```
tarkov-build-optimiser/internal/...
```
.
Keep the package focused; if it grows into two clear domains, consider splitting into two packages only when the boundary is obvious.
Add tests in the same package (
```
*_test.go
```
); use
```
*_unit_test.go
```
or
```
*_integration_test.go
```
per project conventions.

Boundaries to respect

No business logic in cmd/ — cmd only parses flags/env, opens DB, and calls internal packages.
No circular imports — internal packages may depend on each other only acyclically; if you introduce a cycle, extract a shared type or helper into a lower-level package.
Database access — use
```
internal/db
```
for connections and
```
internal/models
```
for SQL and data types; do not add new ad-hoc DB packages.