Skip to content

docs: move the two procedural sections out of CLAUDE.md - #60

Merged
tas50 merged 1 commit into
mainfrom
docs/move-procedures-to-skills
Sep 10, 2026
Merged

tas50 merged 1 commit into
mainfrom
docs/move-procedures-to-skills

Conversation

@tas50

@tas50 tas50 commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Why

CLAUDE.md is read in full at the start of every session, so all ~2,000 tokens of it are paid for on every task. Two of its eight sections are procedures that apply to a small fraction of those tasks:

  • Adding a new service — the recipe for a new service file, used maybe one session in twenty.
  • Linting + PR conventions — only relevant once you are about to commit.

Both move to .claude/skills/, which load only when the task matches. What stays behind are the invariants — the signing and encoding gotchas, and what the test doubles fail to cover. Those stay inline deliberately: a skill only fires when you recognise it applies, and "I am about to silently break request signing" is not a trigger you can recognise in advance.

160 lines → 107.

Lint guidance was stale, and is corrected here

The Linting section predates the golangci-lint CI job (#57):

  • It claimed go vet is in CI and golangci-lint is not. Both are now backwards — .golangci.yml enables govet, which is why the standalone vet step was dropped.
  • The documented golangci-lint run --no-config --default=none -E staticcheck,unused,unparam,revive,bodyclose ./... bypasses .golangci.yml. It enabled unparam and revive, which CI does not run, and skipped errcheck, ineffassign and gofmt, which it does. The skill now documents golangci-lint run ./..., matching CI, plus the second run over the integration/ module that the root run cannot reach.

What deliberately did not change

esc(), asAttributeMap and pathescape_test.go are referenced by CLAUDE.md but exist nowhere on main. They are not stale — they describe #44 and #45, both still open. Removing them would strip the warning about unescaped identifiers ("a name can break the signature or walk into another collection") exactly as the fix for that bug lands. Left intact so they are correct the moment those merge.

The ~96% coverage figure is likewise left alone; main measures 94.6%, and the gap is plausibly those same open PRs.

Test plan

  • go test ./... -race -count=2 clean
  • golangci-lint run ./... reproduces CI — one pre-existing QF1001 on transport.go:34, which is what chore: name the retry condition instead of negating a disjunction #59 fixes
  • Every line removed from CLAUDE.md checked to survive in a skill, or merged into an adjacent bullet deliberately
  • No Go source touched — docs and skills only
  • CI green

🤖 Generated with Claude Code

CLAUDE.md is read in full at the start of every session, so everything in
it is paid for on every task. Two of its sections are procedures that
apply to a small fraction of them: the service-addition recipe and the
lint/PR checklist. Both now live in .claude/skills/, which load only when
the task matches, leaving CLAUDE.md to the invariants a session cannot
afford to miss - the signing and encoding gotchas, and what the test
doubles do not cover.

Correct the lint guidance on the way out. It predates the golangci-lint CI
job: go vet is no longer a separate step, and the documented
--no-config --default=none -E ... invocation bypasses .golangci.yml, so it
enabled linters CI does not run and skipped ones it does.

The esc(), asAttributeMap and pathescape_test.go references stay as they
are. They look dangling on main but describe fix/escape-path-segments and
fix/dig-nested-attributes, which are in review, not code that went away.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Tim Smith <tim@mondoo.com>
@tas50

tas50 commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator Author

CI: test, integration and xgrep pass. lint is red, but not because of anything in this PR — it touches no Go source (CLAUDE.md and two .claude/skills/ files only).

The single finding is transport.go:34:6: QF1001: could apply De Morgan's law, and that line is byte-identical on main. The lint job is red on main itself; #59 is the fix for it. This goes green once #59 merges.

(Apologies for the noise in the previous revision of this comment — a shell quoting slip pasted a tool's help text into it.)

@tas50
tas50 merged commit 121a266 into main Sep 10, 2026
5 of 6 checks passed
@tas50
tas50 deleted the docs/move-procedures-to-skills branch September 10, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant