skill-grade

73% of community Claude Code skills score below 60/100.

Nobody graded them before shipping. Now you can.

skill-grade is a static quality checker for Claude Code SKILL.md files — the same role ESLint plays for JavaScript, but for AI agent skills. It catches missing trigger phrases, scope creep, missing examples, and token bloat before they degrade agent behavior in production.

pip install skill-grade

Quick start

# Grade a single skill
skill-grade path/to/SKILL.md

# Grade all skills in a directory (recursive)
skill-grade ./skills/

# Grade via stdin
cat SKILL.md | skill-grade -

# JSON output for CI pipelines
skill-grade SKILL.md --json

# Fail CI below a threshold
skill-grade SKILL.md --threshold A

Example output

skill-grade v0.1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill: my-skill
Score: 65/100  Grade: C
Tokens: ~847 (description: 312, body: 535)

  W  S006  No trigger phrases detected. Add "Use when...", "Triggers include...",
           or "Use for..." so Claude knows when to invoke this skill.
  W  S013  No code examples (no markdown code blocks). Agents learn better from
           concrete examples than prose descriptions.
  W  S014  No structure detected (no ## headers or numbered lists). Structured
           instructions are easier for agents to follow.

Passed: S001 ✓  S002 ✓  S003 ✓  S004 ✓  S010 ✓  S011 ✓

Tip: A+ skills include explicit trigger phrases and concrete examples.

For multiple files:

skill-grade v0.1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  browser-automation  A+   97/100  ✓
  code-review         B    78/100  1 warning
  deployment          F    35/100  3 errors, 2 warnings

2/3 skills pass (≥70/100)

Checks

Frontmatter

Body

Grades

GitHub Action

- uses: 0-co/skill-grade@main
  with:
    path: '.'
    threshold: 'B'

Or install directly:

- run: pip install skill-grade
- run: skill-grade ./skills/ --threshold B

Why this exists

Claude Code skills are loaded into context when triggered. A skill with a vague description triggers too broadly (wasted tokens) or not at all (the skill gets ignored). A skill with no examples produces worse agent behavior than one with three concrete command invocations.

These are fixable problems. skill-grade makes them visible before they ship.

Zero dependencies

Pure Python stdlib. No PyYAML, no third-party packages. Works anywhere Python 3.9+ is installed.

pip install skill-grade