Improve how skills are written and organized#11
Draft
NagyVikt wants to merge 3 commits into
Draft
Conversation
Run the cue SKILL.md linter (R001-R013) across the library and clear all mechanically-fixable issues: - R001: add missing `name:` (derived from H1) to 7 skills - R005: normalize malformed `allowed-tools:` to `Bash(name:*)` form, keeping real top-level tools (Read, Write, ...) and mcp tools bare - R007: add `category:` (parent dir) to 350 skills missing tags/domain/category - R009: replace em dashes in prose with commas/periods per voice rules (code spans and frontmatter left untouched) Lint diagnostics drop from 1506 to 801; errors from 45 to 1 (the remaining one is a pure-MCP skill the linter's R005 cannot express). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016VVh7dkMEosfyHfvs6qCGv
The README claimed "127 skills across 21 categories"; the library now has 427 skills across 36. Update the headline, the structure tree, and the categories table with accurate per-category counts, and fix the skill-format example to use spec-valid frontmatter (`name:`, `Bash(name:*)` allowed-tools, `category:`) instead of the malformed `["tool_name"]` form the linter rejects. Add a short linting section pointing at the cue linter and the GitHub Action. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016VVh7dkMEosfyHfvs6qCGv
Clear the judgment-level linter findings across the library:
- R004 (194): give every description a trigger phrase ("Use when ...") so
skill discovery can match it. Many descriptions used YAML folded-block
scalars (`>-`) the parser reads as empty; inline them so the trigger is seen.
- R003 (101): tighten over-long descriptions to <=200 chars, keeping the
trigger and the highest-value keywords.
- R009 (banned vocab): reword AI-vocabulary words in prose with plain
alternatives; where a skill lists the banned words as a "don't use these"
instruction, wrap them in backticks (the linter's sanctioned exemption).
Also fix pre-existing frontmatter defects surfaced by validating every block
with a real YAML parser:
- 5 gstack skills had unterminated frontmatter (no closing `---`; an
AUTO-GENERATED comment sat where the delimiter belongs). Add the closing
delimiter and move the comment into the body.
- Quote descriptions containing an unescaped colon so the YAML parses.
All 428 frontmatter blocks now parse as valid YAML. Lint diagnostics drop to
424 (from 1506); the remaining items are info-level (R010/R011/R013), 10
Prerequisites warnings, one broken anchor, and one pure-MCP skill R005 the
linter can't express. No code blocks, `name:`, `allowed-tools:`, or `category:`
fields were altered by the description rewrites.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016VVh7dkMEosfyHfvs6qCGv
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A pass over the whole skill library (428
SKILL.mdfiles) to improve how skills are written and organized, measured against the repo's own linter spec (rules R001–R013).Lint diagnostics drop from 1,506 → 424, and errors from 45 → 1. Every frontmatter block now parses as valid YAML.
Commits
Mechanical lint fixes (
c15e39b) — across 384 skills:name:fields (derived from the H1).allowed-tools:toBash(name:*)form, keeping real top-level tools (Read,Write, …) andmcp__*tools bare.category:to 350 skills that had notags:/domain:/category:.README refresh (
16e710b) — the README claimed "127 skills across 21 categories"; it's really 427 across 36. Corrected the headline, structure tree, and category table, and fixed the copy-paste skill-format example to use spec-valid frontmatter instead of the malformed["tool_name"]form.Description rewrites + frontmatter validity (
dc963aa):>-) the parser reads as empty — inlined so the trigger is visible.---), and several descriptions had unescaped colons.Verification
bun src/index.ts lint-skill skills/— 1 error, 11 warnings, 412 info (all info-level R010/R011/R013 plus 10 Prerequisites warnings, 1 broken anchor).yaml.safe_load).name:/allowed-tools:/category:changed by the description rewrites, and 0 code fences were altered.Known residual
research/trendradaris a pure-MCP skill whoseallowed-toolsthe linter's R005 can't express (it requires aTool(...)paren wrapper, but the skill legitimately uses onlymcp__*tools). Left as-is rather than fake a Bash permission.Out of scope (left for follow-up)
R011 (missing example block, 328), R010 (large shell blocks, 77), R006 (missing Prerequisites, 10), R008 (one broken anchor) — these need per-skill design work rather than mechanical or description-level fixes.
🤖 Generated with Claude Code
https://claude.ai/code/session_016VVh7dkMEosfyHfvs6qCGv
Generated by Claude Code