skillsmith

Lint, score, and visualize fat skill files for Claude Code, the Anthropic Agent SDK, GBrain, and anything else following the SKILL.md + frontmatter + manifest + resolver convention.

One binary. Zero runtime deps for the core. Sub-second against a 26-skill repo.

skillsmith lint   <path>   Validate frontmatter, sections, manifest, resolver, MECE triggers, broken links
skillsmith score  <path>   Score each skill on a 100-point rubric, print top fixes
skillsmith graph  <path>   Self-contained interactive HTML of the skill dispatcher topology
skillsmith mcp              Expose all three as MCP tools over stdio

Install

git clone https://github.com/YOUR_USERNAME/skillsmith.git
cd skillsmith && bun install
bun src/cli.ts --help

# optional compiled binary
bun run build        # produces ./bin/skillsmith

Requires Bun. Works on macOS, Linux, and Windows (WSL).

Demo

Point it at any skills directory. Here it is against garrytan/gbrain's 26-skill brain-ops repo:

skillsmith lint

skillsmith lint — /path/to/gbrain/skills
================================================================
Skills found:  26
Errors:        3
Warnings:      2

skill:install
  ✗ [F1] missing YAML frontmatter (expected --- fenced block at top)
  ✗ [F2] frontmatter missing required field `name`
  ✗ [F3] frontmatter missing required field `description`

root
  ! [X1] duplicate trigger "citation audit" claimed by: citation-fixer, maintain
  ! [X1] duplicate trigger "process this meeting" claimed by: ingest, meeting-ingestion

Every issue has a stable code (F1, F2, S1, M1, R1, X1, X2, ...) so you can wire it into CI or a pre-commit hook.

skillsmith score

Skills: 26    Average: 85.0 / 100

SKILL               SCORE  GRADE  DIMENSIONS
--------------------------------------------------------------------
briefing             92    A      F20 S20 Cl15 E15 Ch7 H15
enrich               92    A      F20 S20 Cl15 E15 Ch7 H15
...
install              25    F      F0  S0  Cl3  E5  Ch7 H10

Legend: F=Frontmatter S=Structure Cl=Clarity E=Examples Ch=Chaining H=Hygiene

Top fixes:
  install (25/100):
    - Frontmatter: missing name; missing description; no triggers declared
    - Structure: no "Contract"; no "Anti-Patterns"; no "Output Format"

The rubric is transparent — every point earned or lost is explained, so the output is a fix-list in disguise.

skillsmith graph

skillsmith graph ../gbrain/gbrain/skills -o skills.html && open skills.html

Self-contained 15KB HTML file. Force-directed layout, draggable nodes, hover for description, click for inbound/outbound chain edges. Mutating skills are red, read-only skills are blue, declared chain_with edges are solid, inline references are dashed.

skillsmith mcp

Expose all three as MCP tools to any agent:

// ~/.claude/server.json (Claude Code)
{
  "mcpServers": {
    "skillsmith": { "command": "skillsmith", "args": ["mcp"] }
  }
}

Tools:

• skillsmith_lint(path, format?)
• skillsmith_score(path, format?)
• skillsmith_graph(path, format?) — returns JSON or HTML

Now your agent can audit its own skills directory before publishing it.

The rubric

100 points across six dimensions. Dimensions chosen because they actually predict whether an agent can pick up a skill and run it.

Dimension	Max	What it checks
Frontmatter	20	name, description, at least one trigger
Structure	20	Contract, Anti-Patterns, Output Format sections
Clarity	15	description length 40–600, 3+ headings, no wall-of-text paragraphs
Examples	15	fenced code blocks + bullet examples
Chaining	15	declares chain_with or mentions sibling skills inline
Hygiene	15	no TODO/FIXME markers, no broken links, frontmatter parses cleanly

Tune the rubric by editing src/score.ts — everything lives in one file.

Lint codes

Code	Severity	What
F1	error	Missing YAML frontmatter
F2	error	Missing required field name
F3	error	Missing required field description
F4	warn	name doesn't match directory name
S0	warn	No headings in body
S1	warn	No "Contract" section
S2	warn	No "Anti-Patterns" section
S3	warn	No "Output Format" / "Output" section
M1	warn	Skill directory not in manifest.json
M2	warn	manifest.json entry points to missing file
R1	warn	Skill name not referenced in RESOLVER.md
X1	warn	Duplicate trigger across skills (MECE violation). Router→delegate pairs (where one skill's description says "router/delegates/dispatcher" and it chain_withs or body-references the other) are exempt.
X2	warn	Broken relative link in skill body

Why skillsmith?

• One binary, no runtime. No React, no CDN, no electron. Pure TS + Bun.
• Works on any skills dir. If you have <name>/SKILL.md, skillsmith works. No coupling to Claude Code, GBrain, or any specific agent runtime.
• CI-friendly. skillsmith lint returns non-zero when there are errors. Wire it into GitHub Actions in two lines.
• Transparent. Every score point and every lint issue explains itself. No magic.
• Agent-auditable. The same tool is available via MCP so agents can self-check before publishing new skills.

Development

bun test          # all tests (parser, lint, score, graph)
bun run demo      # lint + score + graph against ../gbrain/gbrain/skills

License

MIT