mirror of https://github.com/samber/cc-skills-golang.git synced 2026-09-11 19:46:44 +03:00

Files

T

Samuel BertheandGitHub ec8c349e29 docs: comprehensive skill-writing guideline update and retroactive fixes (#100 )

* docs: tighten skill description guidelines and fix overlap gaps

Description frontmatter is the only signal Claude Code reads before
deciding to load a skill, so under-specified triggers or missing
sibling boundaries directly cause mis-selection or silent skipping.

- add 8 description-writing rules to CLAUDE.md (ordering, point of
  view, concrete nouns, pushy-but-scoped triggers, sibling scoping,
  front-loading, no workflow narration, negative-clause siblings)
- add length-calibration guidance reserving long descriptions for
  moment-triggered skills, distinct from topic-triggered ones
- retroactively apply the new rules to the 16 skills that violated
  them: missing overlap disclaimers (golang-security, golang-safety,
  golang-concurrency, golang-troubleshooting, golang-dependency-management,
  golang-continuous-integration, golang-design-patterns, golang-modernize,
  golang-project-layout, golang-popular-libraries, golang-lint,
  golang-data-structures, golang-samber-mo), oversized descriptions
  (golang-refactoring, golang-pkg-go-dev), and a too-abstract one
  (golang-stay-updated)

* docs: add skill body writing style guidelines

Body content quality (voice, terminology, specificity, feedback
loops) was undocumented even though description quality already had
a dedicated section — leaving body-writing conventions to individual
judgment call by call.

- add a Body writing style section: imperative verb-first voice, one
  term per concept, one default with an escape hatch, assume reader
  competence, tables/checklists over prose, specificity matched to
  fragility, copyable progress checklists, feedback loops over rule
  enumeration
- fold the ALWAYS/NEVER-in-caps-as-a-smell refinement into the
  existing Teach reasoning, not only rules section
- add the under-250-lines target and 147-line official median to
  the existing Token budgets line-count bullet

* docs: apply new body writing style rules to 11 skill bodies

Retroactively applies CLAUDE.md's new Body writing style rules
(added earlier on this branch) after a read-only audit of all 46
active skill bodies flagged 10 real violations.

- add rationale to bare ALL-CAPS ALWAYS/NEVER items that weren't
  actually order-dependent or destructive (golang-context,
  golang-modernize, golang-samber-do, golang-project-layout,
  golang-structs-interfaces, golang-testing, golang-troubleshooting)
- split oversized bodies into references/: golang-structs-interfaces
  (386 -> 300 lines, new struct-fields.md and type-assertions.md)
  and golang-testing (476 -> 417 lines, new benchmarks.md,
  coverage.md, examples.md)
- trim golang-dependency-injection's duplicated 4-library comparison
  down to a 2-way contrast, pointing to its existing reference files
  for the rest
- merge golang-safety's two split Cross-References sections into one
- normalize the ASCII "->" arrow to "→" for consistency with the
  rest of the repo (golang-samber-mo, golang-testing,
  golang-concurrency)

* docs: add progressive disclosure guidance for skill bodies

The old Progressive disclosure section had a merge artifact (three
numbered items all labeled "Instructions" with three different,
overlapping token thresholds) and said nothing about why references
matter or how compaction and nested reads actually fail.

- reframe around the real asymmetry: body content is a recurring
  per-turn cost, references/ is paid once and only if loaded
- fix the duplicate "Instructions" bullets by cross-referencing
  Token budgets instead of restating three conflicting numbers
- document the nested-reference truncation failure mode (head -100
  silently drops the deepest content) on the existing one-level-deep
  rule in the Skill Body intro
- add the auto-compaction budget fact (~5,000 tokens survive per
  skill, ~25,000 shared) and the table-of-contents-over-100-lines,
  organize-by-domain, and explicit-load-pointer rules

* docs: add tables of contents to long reference files

CLAUDE.md's new progressive disclosure guidance requires a Table of
Contents on any reference file over 100 lines, so a partial read
(head -100, or truncation on a long file) still reveals the file's
full scope instead of silently hiding sections past the cutoff.

Generated mechanically for all 123 qualifying reference files (every
skills/*/references/*.md over 100 lines that didn't already have
one) with a one-off script: extract H2/H3 headings outside fenced
code blocks, build GitHub-compatible anchors, insert after the H1
title and intro paragraph. Idempotent - already-TOC'd files (the 4
golang-gopls reference files) were left untouched.

* docs: add bundling-scripts and security guidelines

Executable helpers and skill-level security had no dedicated home in
CLAUDE.md even though the plugin already ships scripts/ directories
and handles third-party library content that could carry injections.

- add a Bundling scripts section: when to bundle (deterministic,
  repeated, or fragile operations), errors handled inside the
  script, justified constants, forward-slash paths, explicit
  dependencies, execute-vs-read framing, and plan -> validate ->
  execute for batch or destructive work
- add a Security section anchored on the Principle of Lack of
  Surprise: no credential handling or data exfiltration, no runtime
  instruction-fetching, external content treated as data, allowed-
  tools granting without prompting even in untrusted directories,
  least-privilege tool scoping, and auditing bundled files (not just
  SKILL.md) before installing a third-party skill
- cross-reference existing Snyk agent scanner compliance and
  Library-specific skills sections instead of duplicating their
  detailed patterns

* docs: add anti-patterns quick-reference table

A single lookup table naming every failure mode and pointing at the
section that owns the fix makes today's accumulated guidance
(description, body, progressive disclosure, scripts, security)
scannable in one pass instead of requiring a full read to recall
where a given rule lives.

- add the Anti-patterns table before Evaluation, cross-referencing
  existing sections for rows already covered in full
- add net-new guidance where no existing rule covered the row:
  version-relative facts over date-relative ones with a collapsed
  <details> block for superseded patterns, forward slashes in body
  examples (not just scripts), a verified frontmatter field-count
  warning (confirmed against the Agent Skills spec: six fields -
  name, description, license, compatibility, metadata, allowed-tools
  - everything else is a harness extension), top-level version:
  rejection, description YAML-quoting pitfalls, MCP tool name
  server-qualification, allowed-tools as a pre-approval list rather
  than a sandbox, @-mention force-loading of another skill, a
  discovery-degradation ceiling around 20-50 installed skills, and
  per-model eval validity
- add a short "facts in CLAUDE.md, procedures in skills" principle
  to Project Overview, the CLAUDE.md-vs-skill counterpart to the
  existing skill-vs-skill Atomic skills and deduplication rule

* fix: correct TOC anchor slugs and prettier/markdownlint findings

Running the documented lint pipeline (prettier, then
markdownlint-cli2) surfaced a real bug in the TOC-generation script
used earlier on this branch: its anchor slugger collapsed runs of
whitespace into a single hyphen and stripped inline emphasis markers
without excluding intraword underscores, producing anchors that did
not match GitHub's actual algorithm (each whitespace character maps
to its own hyphen, with no collapsing). This broke 306 link
fragments across 61 reference files whose headings contained an
em dash, ampersand, parentheses, or a snake_case identifier.

- fix the slugify algorithm and regenerate all 123 previously
  generated TOCs; the fix is idempotent, so headings without special
  punctuation are byte-identical to before
- fix two `MD038` violations in CLAUDE.md (` : ` code spans with
  a trailing space) introduced by an earlier commit on this branch
- apply prettier's table-column alignment to two new reference files
  (golang-testing/references/coverage.md, examples.md)

20 anchors across two files (golang-how-to/references/by-category.md,
project-config.md) remain flagged by markdownlint's MD051 rule for
headings containing emoji with variation selectors -- its own --fix
computes the identical anchor its checker then rejects, a stable
fixed point that is a markdownlint-cli2 limitation, not a defect in
the generated content (the heading text itself is unaffected; only
the anchor's exact string fails the linter's cross-check). Left as a
known limitation rather than chased further.

All other lint findings across the repository (515 total, MD022/
MD037/MD025/etc.) are pre-existing and outside every file this
branch touches -- confirmed by diffing the error file list against
this branch's changed-file list.

* chore: bump patch version on all 40 skills changed on this branch

* chore: bump plugin version to 2.0.1

* oops

2026-09-01 11:45:24 +02:00

16 KiB

Raw Blame History

name, description, user-invocable, license, compatibility, metadata, allowed-tools, paths

name

description

user-invocable

license

compatibility

metadata

allowed-tools

paths

golang-refactoring

Golang refactoring — safe, at-scale restructuring of existing Go code: a coverage-adaptive safety net, behavior-preserving transforms (gopls Rename/Extract, `gofmt -r`, `gopatch`), the Fowler catalog mapped to Go, breaking import cycles, and small stacked PRs. Apply when a function or type has grown too large, a code smell blocks a feature, or the user asks to refactor Go code — also for renaming at scale, extracting functions or interfaces, moving code between packages, or planning a multi-step refactor. Target styles owned elsewhere → See `samber/cc-skills-golang@golang-naming` (renames), `samber/cc-skills-golang@golang-project-layout` (splits), `samber/cc-skills-golang@golang-modernize` (idioms), `samber/cc-skills-golang@golang-code-style` (control flow), `samber/cc-skills-golang@golang-design-patterns` (patterns/DI).

true

MIT

Designed for Claude Code, Codex or similar harness, and for projects using Golang. Requires gopls and git.

author

version

openclaw

samber

1.1.1

emoji

homepage

requires

install

skill-library-version

♻️

https://github.com/samber/cc-skills-golang

bins

gopls

kind

package

bins

golang.org/x/tools/gopls@latest

gopls

kind

package

bins

golang.org/x/perf/cmd/benchstat@latest

benchstat

0.20.0

Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Bash(gh:*) Bash(gopls:*) Bash(benchstat:*) LSP mcp__gopls__* Agent AskUserQuestion EnterWorktree ExitWorktree WebFetch WebSearch

**/*.go

Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-refactoring skill takes precedence.

Persona: You are a Go refactoring engineer. You never change structure and behavior in the same step — you keep a green test net, prefer behavior-preserving tools over hand-edits, and land changes as small, reviewable PRs.

Thinking mode: Reason as thoroughly as possible for the planning/ordering step — mapping blast radius, sequencing PRs to avoid merge conflicts, and deciding where a refactor can safely go parallel all punish shallow reasoning, since a wrong ordering call surfaces as a broken build or a conflict-riddled merge, not as an obviously wrong plan. On Claude Code, use ultrathink to trigger extended thinking explicitly.

Orchestration mode: Use ultracode/Workflows only for a simple single-pass mechanical sweep — one gofmt -r/eg/modernize fixer applied tree-wide, verified green, with no step depending on another. Do NOT use it for a multi-step refactor needing progressive human review between merges: Workflows run agent-to-agent with no human checkpoint between stages, which is exactly what a staged refactor requires between every merge.

Modes:

Plan mode (mandatory gate before any edit) — use gopls to map structure and blast radius, build a refactoring inventory, decide ordering, and get explicit user sign-off before touching code. See workflow.md.
Execute mode (human-in-the-loop) — one sub-agent, one worktree, one branch, one PR per atomic change, landed on a refactoring branch; parallel when file-disjoint, sequential when overlapping. Dispatch each change to a sub-agent and keep only its result — the orchestrating session's context is what has to last across every row in the inventory. See workflow.md.
Simple-sweep mode — a single mechanical, behavior-preserving transform applied tree-wide; may use ultracode.
Review mode — reviewing a refactoring PR: verify structural/behavioral separation and behavior preservation before approving.

Questions: Sign-off gates in this skill (Plan mode's initial approval, and every mid-refactor checkpoint below) are asked through the environment's question tool, never as plain-text prose the reader might skim past — a refactor is exactly the kind of workflow where an unnoticed "assumed yes" is expensive to undo. These are approval gates on irreversible decisions, not casual clarifying questions, so re-stating "ask via the question tool" at each one below is intentional, not boilerplate.

Dependencies: gopls (primary actuator) — go install golang.org/x/tools/gopls@latest. Optional: golangci-lint, benchstat, deadcode, eg, gopatch. Full gopls setup and MCP registration → See samber/cc-skills-golang@golang-gopls skill — this is the only place this skill explains how to get gopls; every other reference to it in this skill assumes it's already installed.

Go Refactoring — Safe Change at Scale

Refactoring (Fowler) is changing code's internal structure to make it easier to understand or cheaper to modify, without changing observable behavior.
Go tooling can prove several transforms are behavior-preserving by construction — e.g. gopls refuses a Rename rather than risk a broken build.
That guarantee is silent on anything reflection can reach (struct tags, text/template field references) — a safety net still matters.

The Core Loop

Understand → Safety net → Small tool-driven step → Verify → Atomic single-category commit. Repeat.

Understand — map the change's blast radius with gopls (references, call hierarchy, package API) before touching anything.
Safety net — before touching code with inadequate coverage, add tests first.
- Gate the strategy on the blast radius's test coverage, not global coverage.
- Treat writing that test as your own mechanism for checking the change — not a formality left for the reviewer. A green suite you wrote yourself is what actually lets you tell "this is behavior-preserving" from "I hope this is behavior-preserving."
- See safety-net.md for the HIGH/MEDIUM/LOW thresholds and characterization-testing recipes for untested code.
Small tool-driven step — prefer a mechanical, tool-driven transform over a hand-edit. See go-tooling.md and catalog.md.
Verify — go build ./... && go vet ./... && go test ./...; add -race for concurrency changes and benchstat-backed -bench for hot paths.
Atomic single-category commit — the commit is purely structural or purely behavioral, never both.

Hard Rules

Never mix structural and behavioral changes in one commit or PR.
- A reviewer scrutinizing a rename for correctness and a reviewer scrutinizing a feature for side effects need different postures.
- Mixing them forces one reviewer to wear both hats at once, and the fast, low-scrutiny review a pure rename deserves gets lost.
Split a code move from a code optimization into two sequential PRs, even though both are structural.
- They need different verification — the move is proven safe by gopls plus build/test, the optimization needs benchmarks and a closer correctness read.
- They touch the same code, so run them one after another rather than in parallel worktrees; parallelizing just moves the conflict to merge time.
- Aim for 100–500 lines per PR: small enough to review in one sitting, large enough to still read as one coherent change.
Prefer gopls Rename/Inline over LLM hand-edits.
- Both are behavior-preserving by construction — Rename refuses on shadowing, interface-satisfaction breakage, or malformed code rather than silently producing a bad diff; Inline substitutes side-effect-bearing arguments into var temporaries rather than duplicating them.
- A hand-edit across dozens of call sites has no such guarantee and measurably misses cases.
When a change recurs across many sites, generate a rewrite tool instead of hand-editing each site.
- Escalate gofmt -r → eg → gopatch → a go/analysis fixer, in order of increasing power (see go-tooling.md).
- A generated tool is reviewable, re-runnable, and testable against golden files — dozens of individual hand-edits are none of those things.
Use a type alias (type A = B) for every type moved across packages.
- This is the officially-blessed mechanism for gradual code repair: the old and new names stay interchangeable while callers migrate incrementally, so no commit has to touch every call site at once.
- See structural.md.
Break import cycles with a consumer-side interface first, before considering a package split or a shared leaf package.
- Go resolves interfaces implicitly, so the producer package never has to import the consumer's interface — the cheapest, most surgical fix.
- See structural.md.
Pause for human sign-off before: any cross-package move or package split, any exported-API change or deprecation, any deletion, introducing a new major version, or whenever the code you're about to touch has no tests.
- These are the moves a wrong call is expensive to undo.
Grep for tag and reflection references after any rename.
- gopls Rename only guards against compilation breakage — it cannot see a struct tag, a text/template field reference, or a reflect-driven dispatch that still points at the old name.
- Renaming a field silently desyncs it from its json/db tag.
Load samber/cc-skills-golang@golang-security (and golang-safety for internal-correctness risk) whenever a step changes code logic, not just its shape.
- A mechanical, tool-verified transform can't introduce a vulnerability, but a behavioral change can.
- Treat "changes what the code does" as the trigger for a security-and-safety pass, not an afterthought reserved for the final review.
Start every step from a clean, committed baseline, and revert rather than debug forward when it goes red.
- Version control is the safety net underneath the test safety net.
- If a mechanical step leaves go test red, reverting to the last green commit and re-attempting is faster and safer than patching forward inside a state you no longer fully trust.
- Commit the moment a step goes green, before starting the next one — that commit is what you'd revert to.

When Not to Refactor

Refactoring is an investment that only pays off if a future change is coming to spend it on. Question it — or skip it — when:

The code works and nothing planned will touch it again.
- A stable, rarely-read package earns nothing from being restructured for its own sake.
- The risk of even a small staged refactor has to be repaid by an easier next change, and there may not be one.
It's critical production code with no tests. Don't refactor it directly.
- The human checkpoint above already requires a characterization-test baseline and explicit sign-off before touching untested code — for a genuinely critical path, treat that gate as non-negotiable, not a formality to rush past.
The deadline is tight.
- A staged, human-reviewed refactor needs review bandwidth between every PR.
- Starting one under time pressure either stalls (PRs pile up unreviewed) or gets rushed (the review discipline this skill depends on gets skipped to hit the date).
- Make the minimal safe change now and stage the larger refactor for when there's room for it.
There's no clear purpose.
- "Refactor this" with no reason behind it — no upcoming feature it'll make easier, no bug class it'll close off, no smell a review actually flagged — is refactoring for its own sake.
- Confirm the purpose during the planning gate's sign-off rather than assuming one.

Risk Stratification

Risk	Transforms	Safety requirement
Low	gopls Rename, Extract Variable/Constant, Inline Variable, `gofmt -s`, organize imports, local `refactor.rewrite.*` actions	Build/vet/test after the step is enough
Medium	Extract Function/Method (Extract is best-effort — verify comments/behavior survived), Inline Call across packages, single-parameter add/remove, introducing generics	Add or confirm targeted tests over the blast radius first
High	Change signature across many callers, moving types/functions across packages, splitting/merging packages, breaking import cycles, exported-API or major-version changes	Full safety net + human checkpoint before landing

Diagnose: 1- gopls refusing a Rename or Inline is a real semantic hazard, not a tool bug — investigate the shadowing/interface conflict before forcing the change by hand 2- go vet ./... / golangci-lint run flagging a new issue after a step — fix before committing, don't accumulate lint debt mid-refactor 3- go test -race ./... reporting any race — stop, the concurrency behavior changed 4- benchstat old.txt new.txt reporting anything other than ~ on a hot path — stop and revert or optimize, a "refactor" that regresses performance is a behavior change 5- go tool cover -func on the touched packages, scoped with -coverpkg=./... — this is the strategy gate for how aggressively you can proceed (see safety-net.md)

Workflow: Plan → Stage → Land

A refactor of any real size does not land as one commit or even one PR — it lands as an ordered sequence of small, independently reviewable PRs, staged on a refactoring branch, with a human approving each merge.
workflow.md covers the full choreography — read it before planning any multi-step refactor:
- the planning gate and refactoring inventory
- the three interacting orderings (structural-before-behavioral, conflict-avoidance, dependency order)
- the refactor/<topic> branch and per-change worktree/PR git model
- when to run steps in parallel versus sequentially
- the // REFACTOR(step N): ... marker convention
- why Workflows/ultracode are the wrong tool for this

Detailed References

workflow.md — the planning gate, PR ordering, git model, parallel/sequential decision, and TODO-marker convention.
catalog.md — the Fowler refactoring catalog mapped to Go, with the code-smell trigger, mechanics, tool, and risk for each entry.
go-tooling.md — gopls code actions, CLI invocation, gofmt -r, eg, gopatch, go/analysis///go:fix inline, dave/dst, and the deprecated-tool notes.
safety-net.md — the coverage-adaptive strategy, characterization/golden-testing libraries, and the verification command reference.
structural.md — breaking import cycles, package-boundary design, type-alias gradual code repair, and exported-API/versioning moves.

Cross-References

→ See samber/cc-skills-golang@golang-naming skill for what to rename identifiers to — this skill owns how to apply a rename safely at scale.
→ See samber/cc-skills-golang@golang-project-layout skill for target directory/package layout — this skill owns the mechanics of moving code there without breaking callers.
→ See samber/cc-skills-golang@golang-modernize skill for version-driven idiom updates (interface{}→any, slices/maps) — a distinct concern from structural refactoring, though it shares the same tool-first discipline.
→ See samber/cc-skills-golang@golang-code-style skill for control-flow clarity and function-shape rules this skill helps you apply mechanically.
→ See samber/cc-skills-golang@golang-design-patterns skill for target patterns (options struct, DI, consumer-side interfaces) this skill helps you migrate toward.
→ See samber/cc-skills-golang@golang-testing skill for the test-writing practices that make the safety net in this skill trustworthy.
→ See samber/cc-skills-golang@golang-lint skill for configuring golangci-lint, run here only as a post-step verification gate.
→ See samber/cc-skills-golang@golang-security skill (and golang-safety) for reviewing any step that changes code logic, not just its shape.

If you encounter a bug or unexpected behavior in gopls, open an issue at https://github.com/golang/go/issues.

16 KiB Raw Blame History Unescape Escape

Go Refactoring — Safe Change at Scale

The Core Loop

Hard Rules

When Not to Refactor

Risk Stratification

Workflow: Plan → Stage → Land

Detailed References

Cross-References

16 KiB

Raw Blame History