* 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
* docs: make cross-harness portability the default for skill authoring
Skills in this repo are authored for Claude Code but installed on
Codex, Gemini CLI, Cursor, Copilot and OpenCode. Hardcoded tool names
in skill body prose (via the Agent tool, AskUserQuestion, Glob) only
resolve on the harness they name and degrade silently elsewhere.
- Makes capability-based prose the default authoring behavior, folded
into Allowed Tools, the frontmatter compatibility row, and the
top-of-body directives table, no separate portability section.
- Adds a new optional Questions top-of-body directive so interactive
skills declare it once instead of repeating a hardcoded tool name
at every question.
- Leads Thinking/Orchestration mode directives with the universal
reasoning/fan-out instruction; ultrathink/ultracode are mentioned
second, as the Claude Code-specific accelerator layered on top.
- Adds paths/globs and experimental dependencies as documented
optional frontmatter fields; explicitly does not adopt Antigravity's
turbo_safe field or Mistral Vibe's permission = always equivalent,
since both conflict with this project's confirm-before-risky-action
policy.
- Fixes a malformed inline checklist item in the after-updating-a-
skill workflow and an inaccurate Override-column reference.
Mirrors samber/cc-skills PR 40, applied to this repo's own structure.
This README keeps its Ultrathink/Ultracode columns, which cc-skills
does not have.
* docs: rename Ultracode policy heading to Deep thinking over parallel sub-agents policy
* feat(skills): add ultracode orchestration directive to fan-out skills
The `ultracode` keyword (multi-agent workflow orchestration) didn't exist
when these skills were originally written. Add a Thinking-mode-style
Orchestration mode directive to the 12 skills that already describe a
parallel sub-agent fan-out mode for full-codebase audits/scans/cleanups,
so the agent knows to escalate to orchestration for broad sweeps.
Documents the new directive and its README flag (🤖) in CLAUDE.md, and
bumps each touched skill's patch version.
* fix(skills): bump patch version for security, performance, modernize
main already bumped these three skills to the same patch value for an
unrelated change (isolated-worktree workflow), so the rebase merge
landed on an identical version string and hid this branch own change.
Bump one more patch to reflect this branch additions.
* 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>
Adds a step to the new-skill checklist: dispatch parallel sub-agents to
read existing skills and add a "-> See" cross-reference where their
topic overlaps with the new skill, keeping the atomic-skill ownership
convention from drifting out of sync.
* feat(skills): add isolated-worktree workflow to 5 skills
Document when to use the native EnterWorktree/ExitWorktree tools for
workflows with genuine collision risk: parallel mutating sub-agents
(golang-documentation, golang-modernize), variant comparison with a
serial-measurement caveat (golang-benchmark, golang-performance), and
per-fix remediation branches during large audits (golang-security).
Read-only parallel audits (security scan, testing, troubleshooting,
etc.) were deliberately excluded — concurrent reads need no isolation.
* revert: keep plugin version at 1.7.0
The isolated-worktree workflow changes do not warrant a plugin-wide
version bump on their own.
* revert: drop worktree workflow from golang-documentation
Its parallel sub-agents write independent files/sections rather than
racing on shared state, so isolation is not warranted here.
* 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>
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.
Redesigned 116 eval groups that showed no delta between with/without
skill runs. Three failure modes addressed:
- Both-fail (adversarial override): removed explicit wrong instructions
from prompts; traps now make the wrong approach a natural default
- Both-pass (common knowledge): replaced widely-known patterns with
Go-specific, niche, or counterintuitive scenarios the model misses
without the skill
- Both-partial (mixed assertions): split homogeneous groups, removed
common-knowledge assertions, fixed coverage-gap ones
Also strengthened eval design principles in CLAUDE.md: clearer
adversarial framing rules, pre-flight gate, positive-trigger
preference, training-data saturation heuristic.
- 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
Introduce skill-library-version in openclaw metadata for skills covering
versioned third-party projects. Add workflow in CLAUDE.md for periodically
checking outdated skills against upstream changelogs. Apply to all 15
library-specific skills with latest upstream 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
Barkhayot JuraevandGitHub