Turn your AI agent's skill file into a 100-point checklist

AI agents don’t just read your skills—they carry them in their memory forever. A poorly written SKILL.md doesn’t just go unused; it slowly drains your context window, appearing in every prompt whether relevant or not. Most teams draft these files by instinct and ship them without a second glance. That’s why a new command-line tool is changing the game.

Meet skillscore, a Dart-based CLI that turns vague AI agent skills into measurable, actionable insights. Feed it any SKILL.md file and it returns a 0–100 quality score, a letter grade, and a prioritized checklist of fixes—each one tied directly to the official authoring guides from Anthropic, OpenAI, Google, and Flutter.

skillscore is an open-source, offline linter that validates AI agent skills against industry-standard authoring guides. It runs deterministically, produces CI-ready outputs, and never makes network calls.

From instinct to enforcement: why SKILL.md quality matters

AI skills are becoming the standard way teams extend agents like Claude Code, Codex, or Cursor. A skill is simply a folder containing a SKILL.md file—with YAML frontmatter (a name and a one-line description) and a Markdown body of instructions—plus optional reference files, examples, scripts, and assets.

The hidden cost? Every time an agent loads a skill, the file’s name and description stay in memory. A vague description not only fails to trigger the skill when needed—it actively pollutes every prompt. It’s like keeping a sticky note on your monitor that says "helpful when needed" but never clarifies what "helpful" means.

That’s why vendors publish authoring guides: use third-person language, front-load triggers, state when not to use the skill, keep the body concise, document scripts clearly. Sound advice—but spread across four documents, with no enforcement. Until now.

How skillscore works: 24 rules, one score

skillscore transforms those authoring guides into 24 concrete, checkable rules across seven weighted categories. Run it against a single file, a skill folder, or an entire monorepo and it returns a per-skill score with breakdowns and actionable findings.

dart pub global activate skillscore

skillscore path/to/SKILL.md
skillscore skills/

The scoring breakdown:

• Category A: Frontmatter validity (15 pts): Validates YAML delimiters, required fields, and name format.
• Category B: Description quality (25 pts): Checks for third-person phrasing, front-loaded triggers, and a clear boundary clause (when not to use the skill).
• Category C: Conciseness (15 pts): Flags bloated explanations, long “or” chains, and excessive text.
• Category D: Structure (15 pts): Ensures progressive disclosure, shallow links, and usable tables of contents.
• Category E: Instruction quality (20 pts): Detects workflow anti-patterns, missing checklists, and weak feedback loops.
• Category F: Content hygiene (10 pts): Flags outdated dates, inconsistent terms, and malformed paths.
• Category G: Safety & scripts (up to -15 penalty): Penalizes undocumented scripts or missing safety sections.

Scores are normalized so a 90 means the same thing across all vendor guides. Every finding includes the exact line number and a link to the rule’s source guide—no guessing about why something matters.

Test-drive skillscore on a real Flutter skill

Let’s see it in action. skillscore evaluated a public SKILL.md from the Flutter team’s repository—flutter-add-widget-test—and returned:

flutter-add-widget-test (SKILL.md)
Score: 90/100
Grade: A

A Frontmatter validity 15/15 ██████████
B Description quality 21/25 ████████░░
C Conciseness & token economy 15/15 ██████████
D Structure & progressive disclosure 15/15 ██████████
E Instruction quality 14/20 ███████░░░
F Content hygiene 10/10 ██████████
G Safety & scripts no penalty

WARNING E1_anti_patterns line 8
Body contains no explicit anti-patterns (no "do not", "never", or "avoid").
fix: Add explicit prohibitions, e.g. "Never share a WidgetTester across tests."

INFO B5_boundary_clause line 3
Description has no boundary clause saying when NOT to use the skill.
fix: Append a boundary, e.g. "Do not use for multi-screen integration tests."

The file scored highly—but skillscore pinpointed two easy fixes: adding explicit anti-patterns and a clear boundary clause. Both are documented in the official guides and require minimal effort to implement.

Need deeper context? Each finding supports a skillscore explain command that unpacks the rule’s rationale, the exact fix, and the guide it comes from.

Plug skillscore into your CI pipeline today

A score that lives only on your screen isn’t a gate. skillscore is built for automation:

# .github/workflows/skills.yml
name: Lint agent skills
run: |
  dart pub global activate skillscore
  skillscore skills/ --min-score 80 --no-color

Key features:

• --min-score 80 makes the job exit non-zero if any skill falls below the bar.
• --format json outputs structured data for dashboards or monitoring tools.
• --format sarif generates SARIF 2.1.0 reports that integrate with GitHub code scanning, annotating pull requests at the exact line where findings occur.

Exit codes are pipeline-safe: 0 for success, 1 for gate failure, 2 for usage errors. No flaky LLM calls, no network dependency—just consistent, deterministic scoring.

Why not just ask an LLM to review my skill?

LLMs can suggest improvements, but they’re not validators. skillscore offers three advantages:

• Schema validation: Checks frontmatter structure and required fields automatically.
• Quality scoring: Measures discoverability, structure, and instruction quality—not just grammar.
• Source citations: Every rule links back to the official vendor guide, so you know why something matters.

In short, skillscore turns subjective skill writing into an objective, repeatable process—one that protects your context budget and makes your AI agents smarter from day one.

The future of agent skills isn’t vague—it’s measurable. Start scoring today.