* docs: cap prose paragraphs at 3 sentences and clarify token budgets
CLAUDE.md constrained prose only at whole-file granularity, with three
conflicting per-SKILL.md token numbers and a "why" pattern that
tempted a second sentence per rule. Add a per-paragraph sentence cap,
a budget table clarifying which number measures what, and a mechanical
checker (scripts/check_prose_density.py) wired into the "After
updating a skill" checklist so verbose paragraphs get caught instead
of only whole-file token/line counts.
* docs: rewrite prose paragraphs over the new 3-sentence density cap
CLAUDE.md now caps standalone prose paragraphs at 3 sentences
(scripts/check_prose_density.py). Running it across every skill found
62 flagged paragraphs in 31 skills, dominated by a recurring
"library disclaimer" paragraph repeated near-verbatim across 17
library-specific skills. Restructure each flagged paragraph into
bullets, a table, or a tightened sentence per CLAUDE.md's Formats
guidance, preserving every fact, URL, and cross-reference. Re-scanning
the full repo now reports 0 flagged paragraphs across all skills.
Bump each touched skill's metadata.version by one patch version.
Update README token counts for the 31 touched skills to match.
* docs: drop the prose-density checker script
The script added mechanical enforcement but no CI wiring, so it never
ran anywhere but ad hoc. Keep the 3-sentence prose cap and the
clarified token-budget table in CLAUDE.md; drop the script and its
two call-outs, renumbering the "After updating a skill" checklist
back to a contiguous sequence.
* 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
Version bumps kept out of the content PRs (#91, #92, #93, #94) so
those stay reviewable on their own merits. This is a standalone
release marker: every skill moves to its next minor version, and the
plugin manifests (.claude-plugin, .cursor-plugin, gemini-extension)
move to 2.0.0 together.
* docs: broaden compatibility base string across all golang-* skills
Replace "Claude Code or similar AI coding agents" with "Claude Code,
Codex or similar harness" per the cross-harness portability rule in
CLAUDE.md, mirroring samber/cc-skills-golang#91.
* feat: scope Go-file skills with the paths frontmatter field
Adds the optional paths frontmatter field (documented in
samber/cc-skills-golang#91) to every skill whose subject matter is
Go source itself, so Cursor can sharpen triggering to **/*.go files.
Skills not tied to a file type (setup, CI, ecosystem-lookup,
orchestrator) are intentionally left without it.
golang-lint also scopes to .golangci.yml, since linter configuration
is as central to that skill as the Go source it lints.
* docs: drop hardcoded Agent-tool phrasing from skill body prose
Continues the cross-harness portability rule from
samber/cc-skills-golang#91 — sub-agent fan-out is a capability every
harness resolves its own way; naming Claude Code's Agent tool in body
prose is redundant on Claude Code and dead weight elsewhere.
* feat(golang-how-to): flatten Configure mode to 5 harnesses, fix Cursor bug
Configure mode previously wrote to CLAUDE.md, AGENTS.md,
.cursor/rules, and copilot-instructions.md with Claude Code framed as
the primary target. This flattens the harness list to equal standing
and adds GEMINI.md (Gemini CLI, Antigravity).
Fixes a real bug: .cursor/rules is a directory of .mdc files with
their own YAML frontmatter, not a single markdown file to grep and
append to. The old Step 2/4 logic assumed the latter and would not
have worked on Cursor. Adds a dedicated .mdc template
(assets/cursor-go-skills.mdc) and a Cursor-specific write path.
Also adds the new Questions top-of-body directive and drops the
remaining hardcoded AskUserQuestion/Glob/Edit tool names from
project-config.md and golang-project-layout's checklist, per the
cross-harness portability rule in samber/cc-skills-golang#91.
* docs(golang-continuous-integration): label CI review blocks as generated artifacts
Notes that the Claude Code and Copilot review blocks under
'AI-Driven Code Review' are generated artifacts targeting a CI
runner, not the developer's local harness — their literal tool names
and permission flags are intentional under the exemption in
samber/cc-skills-golang#91, so a future portability grep hit there
reads as expected rather than as a miss.
* docs: lead Thinking/Orchestration mode directives with universal instruction
Rewords the 8 Thinking mode and 12 Orchestration mode directives across
these skills to lead with the harness-neutral instruction ("Reason as
thoroughly as possible...", "Fan out N parallel sub-agents...") and
mention ultrathink/ultracode second, as the Claude Code-specific
accelerator rather than the instruction itself. Also drops the
remaining hardcoded "(via the Agent tool)"/"(Agent tool)" parentheticals
and EnterWorktree/ExitWorktree tool-name mentions from body prose in
favor of "an isolated worktree" — the tool stays declared in
allowed-tools, prose just describes the capability.
Mirrors the format adopted in samber/cc-skills-golang#91.
* docs: add Questions directive to golang-refactoring and golang-modernize
golang-refactoring gates several irreversible git operations behind
explicit sign-off (initial plan approval, then per-checkpoint mid-
refactor pauses). Adds a top-of-body Questions directive naming the
mechanism once, and removes a verbatim-duplicated 5-item checkpoint
list between SKILL.md and references/workflow.md — workflow.md now
points back to SKILL.md's list instead of restating it.
golang-modernize already had an ad hoc "Consent check" block for its
contextual-trigger mode, placed after the first heading rather than
with the other top-of-body directives. Renames it to the Questions
directive and moves it up next to Persona/Orchestration mode/Modes,
consistent with the convention in samber/cc-skills-golang#91.
* docs(golang-gopls): generalize MCP registration and settings storage
The MCP registration section named only Claude Code's 'claude mcp add'
command with no acknowledgement that gopls mcp is a harness-agnostic
launch command any MCP-capable host can point at. Notes the underlying
command is portable and that other harnesses use their own settings
file rather than a shared config format.
Also drops a stray 'Store the settings in CLAUDE.md' pointer for
gopls's editor-agnostic LSP settings — there was no reason that one
was Claude Code-only.
* chore: bump metadata.version on every skill touched by this branch
Patch bump per CLAUDE.md's version-discipline rule — no plugin
manifest version change, per standing preference to leave
.claude-plugin/plugin.json, .cursor-plugin/plugin.json, and
gemini-extension.json untouched for skill-level updates.
* docs: refresh README token counts for all touched skills
Re-measured Description/SKILL.md/Directory token counts via
tiktoken-cli after the cross-harness portability changes across all
46 golang-* skills.
* Revert "chore: bump metadata.version on every skill touched by this branch"
This reverts commit 28e6c898f0.
* docs(golang-gopls): name CLAUDE.md/AGENTS.md explicitly
Generic 'the project's agent-config file' phrasing lost the concrete
examples the equivalent line elsewhere in the repo keeps. Names the
two most common files while keeping 'or equivalent' for the rest.
* feat(skills): add golang-gopls skill
Documents gopls (the official Go language server) as its own atomic
skill: the three ways to reach it (its MCP server, Claude Code's
native LSP tool, and its CLI), a capability-to-tool matrix, the full
feature catalog (navigation, diagnostics, refactors, web features),
and the efficient read/edit workflows from gopls's own MCP
instructions.
golang-how-to previously carried this content inline; it's now
reduced to a pointer, and the ~18 library skills that referenced
gopls navigation through golang-how-to are repointed to golang-gopls
directly, keeping each concept owned by exactly one skill.
* revert: do not bump plugin version for this PR
* refactor(skills): tighten golang-gopls, drop LSP-server-hosting CLI flags
Moves the capability-to-tool matrix out of SKILL.md into its own
references/matrix.md, cutting SKILL.md from ~3.5k to ~2.3k tokens
while keeping every row. Drops mentions of gopls's attached MCP mode
and the mcp -instructions flag, since neither applies to this skill's
agent-only usage. Trims the CLI global flags table down to the ones
that matter outside of running gopls as a long-lived LSP server
(-listen, -remote*, -debug, -otel, -mode removed), and documents the
remaining flags' full value sets exhaustively.
Also fixes the README's [!IMPORTANT] alert blockquote, which a prior
prettier run had collapsed onto one line, and adds golang-gopls to
the ASCII skill map.
* docs(skills): clarify difference between godig/pkg.go.dev and gopls LSP server
golang-how-to now documents wiring gopls for Go code navigation, both as an
MCP server (agent-first: go_search, go_file_context, go_package_api,
go_symbol_references, go_diagnostics, go_vulncheck) and via Claude Code's
native LSP tool (ENABLE_LSP_TOOL=1 plus the official gopls-lsp plugin).
golang-pkg-go-dev now spells out when to reach for godig (published
ecosystem: versions, docs, importers, CVEs for packages not yet added) vs
gopls (your resolved local build) vs Context7 (fallback for libraries not
indexed on pkg.go.dev), with a task-to-tool matrix.
* fix(skills): route library skills to godig/gopls instead of Context7
17 library skills recommended Context7 as the discoverability fallback
for Go package facts, when godig (pkg.go.dev) and gopls (local code
navigation) are the better-suited tools for those tasks. Each skill's
disclaimer now points to golang-pkg-go-dev (godig) for package docs,
versions, symbols and vulnerabilities, and to golang-how-to (gopls)
for navigating the library's usage in local code, keeping Context7 as
a fallback for docs not indexed on pkg.go.dev. allowed-tools grants
Bash(godig:*), Bash(gopls:*), LSP, and mcp__gopls__* accordingly.
* fix(skills): route golang-popular-libraries to godig/gopls for exploration
The library-selection skill only referred developers to generic library
docs. Add godig for vetting candidate package facts (docs, symbols,
versions, importers, vulnerabilities) and gopls for browsing a
candidate library resolved source once added to the build, keeping
Context7 as a fallback for docs not indexed on pkg.go.dev.
* chore(skills): bump golang-graphql to v0.1.0
* fix(skills): grant gopls CLI and MCP tools in golang-how-to allowed-tools
The skill documents both the gopls MCP server and the native LSP tool
but only granted LSP, not the gopls MCP tools or the gopls CLI itself.
* docs(skills): move godig vs gopls vs Context7 boundary into golang-how-to
The comparison lived in golang-pkg-go-dev, but golang-how-to already owns
gopls wiring and is the orchestrator every Go task loads first, so the
tool-choice guidance belongs there instead. Also added govulncheck as a
fourth compared tool, distinguishing the whole-tree CI audit from gopls
go_vulncheck single-build check. golang-pkg-go-dev now carries a short
pointer instead of duplicating the table.
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* feat(skills): add golang-pkg-go-dev skill
Add a skill covering godig, a pkg.go.dev API client (CLI + MCP server)
for exploring Go packages and modules: docs, symbols, versions,
importers, licenses, and known vulnerabilities. Positioned to be
triggered in place of Context7 for Go packages.
- Complete project-required frontmatter (license, compatibility,
metadata/openclaw, user-invocable, allowed-tools)
- Cross-reference from golang-dependency-management
- Register in golang-how-to loading table + by-category reference
- Add row and description in README
* fix(skills): satisfy CI on golang-pkg-go-dev
- Fix markdownlint MD034/MD060 in sample-output tables
- Remove explicit MCP tool-calling instructions from the body
(drop the "MCP tool" column, keep MCP mentions passive) per the
W001 convention in CLAUDE.md
- Bump golang-how-to (1.0.1) and golang-dependency-management (1.2.4)
metadata.version (both modified)
- Bump plugin version to 1.6.0 in the three plugin manifests
- Update README token count
* chore: re-trigger CI
* feat(skills): cross-reference golang-pkg-go-dev across the catalog
Point library/tool skills and discovery-oriented skills to
golang-pkg-go-dev so pkg.go.dev lookups (docs, versions, symbols,
importers, vulnerabilities) are routed there instead of generic
Context7 doc fetching for Go packages.
- Family A (17 library skills): append a golang-pkg-go-dev pointer to
the "Context7 can help as a discoverability platform" disclaimer
- golang-popular-libraries: vet candidates via pkg.go.dev; use the
imported-by count as a popularity / indirect-quality signal
- golang-security: look up a module's known CVEs without a full scan
- golang-stay-updated: query versions/docs/vulns from the CLI
- golang-documentation: inspect how a published package renders
- Bump metadata.version on all 21 modified skills
- Refresh README token counts (incl. stale how-to / dependency-management rows)
* feat(skills): sync golang-pkg-go-dev with godig v0.1.0
Reviewed the godig CLI/MCP surface (v0.1.0) and updated the skill:
- New commands: dependencies, major-versions, symbol doc, symbol
examples, package imports, version
- Fix: `package info --imports` is now the `package imports` subcommand
- Document global flags (--base-url, --timeout, --log-level) + GODIG_* env
- Make --version / --module first-class per-command flags
- Add a Filter syntax section (operators, string functions, fields)
- Move sample output to references/sample-output.md and refresh formats
(overview, package info, versions, module info gained fields)
- Add skill-library-version 0.1.0; bump skill to 1.1.0
- Refresh README token counts
* chore(skills): keep golang-pkg-go-dev at initial version 1.0.0
* feat(skills): parallel lookups + package-lookup cluster boundary
- golang-pkg-go-dev: instruct parallel godig lookups (batched calls or
sub-agent fan-out) when querying docs/examples/versions for multiple
symbols, packages, or modules
- golang-how-to: add the "Package lookup / discovery" competing cluster
(pkg-go-dev vs popular-libraries vs dependency-management vs security)
to SKILL.md and disambiguation.md
* docs(skills): sync golang-pkg-go-dev with godig v0.1.1
Reflect v0.1.0 -> v0.1.1 changes:
- document exit codes (0 success, 1 runtime error, 2 usage error)
- replace flat filter field list with per-command filterable fields table
- drop undocumented matches() regex; fix example to hasPrefix()
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Revert "Potential fix for pull request finding"
This reverts commit f5e1a19544.
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Add a **Dependencies:** block at the top of each skill body (after directives,
before the first heading) listing install commands for required binaries.
Update CLAUDE.md to document the new top-of-body directive.
Skills updated: golang-benchmark, golang-continuous-integration,
golang-dependency-management, golang-google-wire, golang-grpc, golang-lint,
golang-performance, golang-security, golang-swagger, golang-testing,
golang-troubleshooting.
Skills need user-invocable: true to work correctly when installed as a
Claude Code plugin. Updated 25 SKILL.md files that had it set to false.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add AskUserQuestion to the allowed-tools documentation table in
CLAUDE.md and to the allowed-tools frontmatter of all 24 existing
skills, enabling skills to clarify user intent before proceeding.
Bump patch version for all affected skills and plugin (1.2.3 → 1.2.4).
Samuel BertheandGitHub
