The index-freshness gate raced update-index.yml. Both trigger on a push to
main touching skills/**, so a merge that adds a skill runs the check against
the pre-merge index.json while update-index.yml is regenerating it. Merging
#129 turned main red for about fourteen minutes before the next push cleared
it, with nothing actually wrong.
The check still does its job where it matters - on pull requests, where the
contributor is the one who has to regenerate. On main, update-index.yml is
the mechanism that keeps it current, so verifying it in parallel only ever
produces a false red.
The description is the only signal an agent sees at discovery time, so
overlapping descriptions cause misrouting. Nothing in CI checked for that.
- tools/lint-descriptions.py enforces name==folder, description <=1024
chars, terminal punctuation (a truncation canary), a trigger clause, a
negative trigger, and a 500-line body cap. Pre-existing failures are
grandfathered in tools/lint-baseline.json so this blocks new debt only;
the baseline may shrink and never grow.
- tools/detect-collisions.py scores every description pair by TF-IDF
cosine and ratchets the count of unreviewed near-duplicates. It strips
negative-trigger clauses before vectorizing: those name the sibling
skill on purpose, so scoring them would make correct disambiguation
raise a pair's similarity.
- wire both into validate-skills.yml, along with agentskills conformance,
an index.json freshness check, and a guard that fails the build if a
regex frontmatter parser is reintroduced.
- broaden the path filters from tools/validate-skill.py to tools/**, as
noted when #105 merged.
All five gates verified to fail on deliberately broken input.
Add tools/validate-skill.py and the workflow file to the push/pull_request
path filters so edits to the validator or workflow re-run validation, and
add workflow_dispatch for manual runs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Issues found in review:
1. tools/validate-skill.py: parse_frontmatter operated on the stripped line, so
an indented nested `name:` (under framework-mapping lists, e.g.
`name: 'Create Fake Materials: Fake Website'`) clobbered the skill's
top-level `name`. That produced 94 spurious "invalid kebab-case name"
failures out of 762. Now indented (non-list) key lines are ignored, so only
top-level keys define frontmatter fields. Result: 762/762 pass.
2. Two divergent validators: the CI workflow had its own weaker inline parser
(no subdomain/tag/description checks) requiring a different field set than
tools/validate-skill.py. CI now delegates to tools/validate-skill.py --all
(single source of truth); REQUIRED_FIELDS aligned to include
version/author/license. The duplicate-name and stats steps are unchanged.
3. README: added an explicit authorized-&-lawful-use disclaimer next to the
existing "not affiliated with Anthropic" note, since the library ships
offensive/dual-use techniques.
No skill content changed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mahipal
Daytona39264andCopilot
Homan AnsariandClaude Opus 4.8
mukul975