Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced
nothing. Vale's exit code keys on error-level alerts alone: five of the
six rules were level: warning, so they exited 0, and pre-commit hides
output from a passing hook — the alerts were invisible and blocked
nothing. ADR-0013 rejected a report-only trial tier and then shipped one
by accident.
Flatten every rule to level: error. Vale's own exit code is then correct,
so the hook entry drops to a bare vale-wrap.sh call and the graded
error->FAIL / warning->SUGGESTION mapping disappears from both audit
skills: every alert is a FAIL, in the gate and the audit alike. No
ignorable tier, matching shellcheck, the test suite and
conventional-pre-commit.
Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent
files as they stood before the rule ever ran: 2 hits. One marginal
("very different" -> "fundamentally different"), one an unfixable false
positive — caveman/SKILL.md quotes "of course" as an example of filler,
a mention not a use — which forced the only Vale suppression comments in
the repo. Those four lines go with it; two of them were dead anyway,
suppressing a frontmatter-scoped rule on a body line. Held-out prose (273
files) fired 15 times, 9 inside out-of-scope research examples and the
rest one word in two idioms in a single doc. SentenceOpenerThereIs
survives: 22 held-out hits, both in-corpus hits clean rewrites, zero
suppressions.
Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and
[**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's *
crosses /, so they already matched docs/research/examples/**/agents/*.md
and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they
excluded. Scoping is and was the hook's files: regex. The old globs also
hid a silent false negative: a skill outside plugins/ matched no section,
so Vale reported 0 files and exited 0, which both audits read as clean.
They now treat a 0-file run as NOT RUN and fall back to full judgment.
Also:
- vale-wrap.sh resolves relative --config values and file arguments
against the caller's cwd, as vale does, instead of the repo root, which
hard-errored from a subdirectory and silently skipped flattening for
file args that did not resolve from the root. Absolute paths inside the
cwd are relativized so reports cite resolvable paths, not scratch ones.
- vale-run's exit-code model was documented backwards ("exits non-zero
whenever it finds an alert at or above MinAlertLevel") and would have
led anyone following it to build a gate that passes everything. Its
Markdown suppression syntax was MDX-only and does not suppress in .md;
corrected in the skill and its troubleshooting reference, with
backtick/fence exemption documented as the first resort.
- skill-size-check.sh fails only above 500 lines, agreeing with
skill-audit's validate.sh <= 500 pass.
- ADR-0013 and CONTEXT.md amended to match, recording why graded
severities cannot gate.
Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter,
skill-size-check and shellcheck pass --all-files; check-manifests and
claude plugin validate --strict clean. New tests fail against the old
script (3 of them) and pass against the new one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Addresses PR #85's outstanding review items after grilling the open
questions against ADR-0013/CONTEXT.md/ADR-0010:
Blocking fixes:
- vale-wrap.sh: replace json.dumps() escaping (which silently defeated
Vale's frontmatter scope on any description containing a quote,
backslash, or non-ASCII char — ~58% of the corpus) with a single-quoted
YAML scalar, substituting a Unicode right single quote for embedded
apostrophes rather than '' doubling (Vale's frontmatter scanner isn't a
full YAML parser and silently truncates on '' too).
- vale-wrap.sh: fix a blank-line-inside-a-folded-description truncation
bug via indentation-based, blank-line-tolerant body capture; narrow
flattening to `>`-style scalars only (`|` already works unflattened).
- skill-audit/agent-audit Step 1: make the vale-wrap.sh invocation
cwd-independent via git rev-parse --show-toplevel, fixing a bug where
no single cwd satisfied all three Step 1 commands.
- styles/Kyberforge/VagueQualifier.yml: prune 17 tokens verified
false-positive-dominated on this repo's own voice via a real corpus
sweep (obvious, clearly, usually, several, simple, easy, completely,
simply, tiny, etc.), keep 13 with real or unattested noise. Revert the
28 prose "fixes" those tokens drove across 14 skill files back to their
original, correct wording, including a functional regression to
caveman/SKILL.md's own filler-word list (a mention, not a use) — now
guarded with vale-off comments against recurrence.
Gaps:
- --minAlertLevel=warning on the pre-commit hook and Step 1 invocation
so warning-level rules actually surface, without collapsing the
FAIL/SUGGESTION severity mapping skill-audit/agent-audit rely on.
- vale-wrap.sh: fix --config=<path> equals-form, absolute-path silent
no-op, and a zero-file-argument stdin hang.
- Route vale-run and lint-runner through a documented wrapper script
when a target repo has one, instead of unconditionally recommending
bare `vale`.
- Wire Kyberforge.VagueQualifier/SentenceOpenerThereIs into skill-audit/
agent-audit's dimension-mapping prose (Body discipline).
- Add plugins/lint/sources.md provenance for lint-runner (ADR-0010).
- Sync both marketplace.json lint-entry descriptions with plugin.json.
- Retune skill-size-check.sh's MAX_WORDS 5000->2900 (measured ~1.6-1.7
tokens/word on this repo's corpus, the old value gated at ~8,500
tokens against a stated 5,000 ceiling); fix the >/>= line-count
boundary and wc -l undercount on files with no trailing newline.
- Document the vale binary as a Setup prerequisite in AGENTS.md.
- Fix SentenceOpenerThereIs's dead regex alternative and add a real
sentence-start anchor/scope.
- Fix a stale docs/research/docs/vale/ index pointer in kyberforge's
docs README (moved to plugins/lint/ in e1a5403).
- Rewrite ADR-0013's Consequences section past-tense to describe what
actually landed, and record the styles-portability limitation
(repo-root placement stays intentional; deferred to a separate
session per this PR's review).
Test coverage: 9 new vale-wrap.sh fixtures (quotes, backslash/unicode,
blank-line paragraphs, --config= form, zero-arg/absolute-path handling,
literal-block no-regression) and boundary-pair tests for
skill-size-check.sh's line/word ceilings.
bash tests/run-tests.sh: 9 scripts + 125 bats assertions, all passing.
scripts/check-manifests.sh and claude plugin validate --strict: clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Vale's text.frontmatter.description scope silently stops matching once
the description is a YAML block scalar spanning 2+ physical lines —
the style used by most skills/agents in this repo. scripts/vale-wrap.sh
flattens the description to one line in a scratch copy (preserving the
repo-relative path and total line count) before invoking real vale, and
both audit skills plus the pre-commit hook now call it instead of vale
directly. Also tightens the pre-commit hook's file glob to single path
segments so it can't cross into docs/research examples or asset
templates the way the audit skills' scoped invocations already avoid.
Addresses PR #85 review feedback.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
Adds repo-root .vale.ini plus a custom Kyberforge style (description-opener,
vague-wording, and generic reference-pointer padding rules) and a
KyberforgeCopilot style scoped to .agent.md files (Use proactively check).
skill-audit and agent-audit Step 1 now run vale against the specific file(s)
being audited and defer the corresponding Description/Patterns/Body checks
to its output instead of re-deriving them by LLM judgment, per the split
proposed in issue #84.
Closes#84
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
skill-audit/agent-audit now proactively trigger after a skill/agent
file is hand-edited outside skill-author/agent-author, not just on
explicit request — closing a gap from this session where a fork's
direct edits to agent-author/agent-audit shipped without their own
inline audit until forge was invoked to check afterward.
Also: plugin-author gains a gotcha on claude plugin validate --strict
auto-discovering every .md under agents/ regardless of manifest
declarations (ADR-0010); agent-audit's dimension count and
validate-provenance.sh's --help now match actual behavior.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
skill-audit description understated its coverage by omitting three audit
dimensions (patterns, scripts, provenance); README carried the same stale
list. skill-author had an unconditional reference trigger that should be
conditional on whether a script is being added.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
references/sources.md Research doc: fields are development-only provenance
pointers, not runtime references — they intentionally target paths outside the
skill directory and are expected to be non-resolvable after plugin install.
validate-provenance.sh degrades gracefully when they don't resolve.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add validate-provenance.sh and validate-provenance.bats to enforce the
sources provenance chain introduced by skill-author. Eight checks cover
slug cross-references, Contributing files existence, bidirectional
source_keys linkage, Research doc: field presence, and upstream research
doc alignment (forward INFO, reverse FAIL). Adds a new Provenance report
dimension and INFO finding level (observational, exit-0, counted
separately as · P info in the result block).
Closes#8
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Records the upstream agentskills.io sources that informed skill-audit,
continuing the research → docs → skill provenance chain.
- New references/sources.md with 7 extracted sources attributed to skill files;
agentskills-llms-txt demoted to discovery-only comment per skill-author precedent
- source_keys frontmatter added to SKILL.md (5 slugs), references/body-discipline.md
(agentskills-spec, agentskills-best-practices), and references/description-quality.md
(agentskills-spec, agentskills-optimizing-descriptions)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- validate.sh: move FAIL lines and failure summary to stdout; stderr
reserved for fatal script errors only (missing SKILL.md, bad args)
- skill-audit SKILL.md: replace concrete plugins/kyberforge/skills/...
example with abstract placeholder to fix meta-circularity
- skill-write SKILL.md: rephrase placeholder section-heading instruction
to remove embedded FILL IN: from a code span, clearing validator false positive
- skill-improve SKILL.md: wrap Step 2 root-cause example in a text fence
- skill-write assets/templates/README.md: update Files table to individual-
file rows so skill-audit can verify per-file coverage
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- skill-audit: remove contradictory skip clause in Step 2 (binary only)
- skill-improve: drop redundant "Fix the root" heading; keep specific directive
- skill-write: add section-rename guidance to body discipline step
- template SKILL.md: make Instructions heading an explicit FILL IN placeholder
- template README.md: remove "Invoke via your agent tool:" prefix to match convention
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- skill-audit: promote internal-working gotcha to ## Gotchas section;
narrow cross-plugin path check to exclude tests/ (dev-only, repo-level
deps are expected); require tests/README.md to declare that dependency
- skill-write/skill-improve: reorder descriptions to lead with "Use when..."
for consistency with skill-audit and the agentskills.io spec trigger pattern
- skill-write: add tests/README.md with self-contained bats setup instructions;
remove cross-skill reference to skill-audit's tests/README.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Both validate.bats and new-skill.bats constructed SCRIPT using
$(dirname "$BATS_TEST_FILENAME"), which resolves to tests/ — causing
every test to fail with file-not-found. Fixed to use
$BATS_TEST_DIRNAME/../scripts/ to reach the actual scripts/ directory.
Also clarifies that bats-support/bats-assert must be installed from the
repo root (not the skill root) to match where the tests load them from,
and adds text language tags to three output-template code blocks in
skill-audit's SKILL.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Move test infrastructure (validate.bats, new-skill.bats) from scripts/ to
tests/ — the spec defines scripts/ as executable code agents can run, so
test files don't belong there. Add tests/README.md placeholders with
bats-support dependency declaration.
Update skill-audit to permit tests/ and flag other unlisted directories,
add scripts/ purpose check, and add /skill-improve near-miss exclusion.
Update skill-improve and skill-write to cover tests/ in directory lists,
scaffold template, and authoring guidance.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace verbose three-pass output (punch list + priority table + fix
proposals) with a compact findings-only report: coverage line, findings
grouped by dimension with Why+Fix per entry, and a result block with
/skill-improve handoff. Suppress PASS lines — absence confirms pass.
Fix validate.bats executable bit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Reorder skill-audit description to lead with 'Use when...' trigger (P3)
- Add concrete example to 'control calibration' body discipline check (P4)
- Add bats test files to README file tables for both skills
- Fix REPO_ROOT and SCRIPT paths in bats files after tests/ subdirectory removed
- Add three lessons: plugin cache isolation, spec-grounded rubrics, test file placement
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add references/description-quality.md and references/body-discipline.md to
skill-audit — condensed, rubric-focused extracts from the agentskills.io
specification docs. Both files are loaded conditionally via progressive
disclosure triggers added to Step 3 (Description and Body discipline
dimensions), so the agent consults the spec source when a finding is
borderline rather than relying solely on inline heuristics developed
during the skill-write authoring cycle.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Move validate.sh ownership to skill-audit/scripts/ — it is the canonical
structural validator; skill-write now delegates Step 5 to /skill-audit
- Add skill-write/references/scripts.md and deployment-modes.md for progressive
disclosure of package runner patterns and plugin cache isolation rules
- Fix skill-audit Step 1 cross-skill path reference (was repo-absolute, now
skill-relative); add manual fallback for sandboxed/Bash-denied contexts
- Scope Step 2 "read every file" to exclude binaries and unreferenced files
- Fix new-skill.sh next-steps output to reference /skill-audit instead of
the removed validate.sh
- Remove stale Dependencies section from skill-audit README; flip dependency
arrow — skill-write depends on skill-audit, not vice versa
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rewrote the skill authoring factory skill from scratch against the agentskills.io
specification. Renamed write-skill → skill-write (name now matches directory per spec).
skill-write:
- Full scaffold via new-skill.sh (annotated templates for SKILL.md, README.md,
scripts/, references/, assets/)
- validate.sh checks all spec constraints deterministically (name format/length,
description length, placeholder detection, line count, script rules)
- SKILL.md body includes description rules, body discipline, patterns, and scripts
guidance with "why" rationale throughout
- Templates usable standalone by agents and humans
skill-audit:
- Structural validation (via validate.sh) + seven qualitative dimensions
- Produces PASS/FAIL/SUGGESTION punch list with per-FAIL fix proposals
- Report-only: does not apply fixes
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
