* 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.
Recompute Description/SKILL.md/Directory token counts for every skill
with tiktoken-cli (several skills grew since the last measurement, e.g.
golang-continuous-integration's assets/, golang-how-to's references/).
Also add missing golang-pkg-go-dev to the skills tree diagram.
* fix(skills): refresh golang-pkg-go-dev for godig v0.2.0
Sync the skill with the godig v0.2.0 CLI surface (was written against v0.1.0):
- vulns now reads the Go vulnerability database (vuln.go.dev, OSV) instead of
pkg.go.dev, so summary and per-range fix versions are populated. It dropped
--filter and --module (only --version and --limit remain).
- Document the new global --vuln-base-url flag.
- Drop vulns from the --filter command list, its filterable-fields row, and the
now-obsolete "vulns uses Go-style ID/Details" casing caveat.
- Update the sample vulns output (fixedVersion removed; ranges/aliases added).
Bump skill 1.0.0 -> 1.1.0, skill-library-version 0.1.0 -> 0.2.0, plugin 1.6.0 -> 1.7.0.
* docs(golang-pkg-go-dev): clarify vulns data source in sample-output intro
Addresses PR review: the intro claimed all field sets mirror the pkg.go.dev
API, but since v0.2.0 vulns is sourced from the Go vuln DB (vuln.go.dev).
* 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>
- Replace imperative "search for latest version / check URL" instructions
with passive availability hints in golang-continuous-integration,
golang-dependency-management, golang-modernize, and golang-samber-ro
- Replace `go install govulncheck@latest` with golang/govulncheck-action@v1
in CI security asset (W012)
- Remove `gh repo view` from dependency evaluation checklist (W011)
- Add golang-performance step: paste benchstat output in commit body
- Document W011/W012/W001 fix patterns in CLAUDE.md for future authors
- Add snyk-agent-scan step to the "After updating a skill" workflow
- Bump plugin to v1.2.5; bump affected skill versions
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
