From 9469b7c56b90d11ccb3075bce95fd724743619cf Mon Sep 17 00:00:00 2001 From: Olga Safonova Date: Wed, 11 Mar 2026 15:54:57 +0100 Subject: [PATCH] feat: add skill-check for agentskills.io spec validation (#263) * feat: add skill-check for agentskills.io spec validation Read-only skill that validates SKILL.md files against the agentskills specification and Anthropic best practices. Catches structural errors, semantic contradictions, naming anti-patterns, and quality gaps. Source: https://github.com/olgasafonova/SkillCheck-Free License: MIT Co-Authored-By: Claude Opus 4.6 * Add ## Overview section per canonical template Co-Authored-By: Claude Opus 4.6 --------- Co-authored-by: Claude Opus 4.6 --- skills/skill-check/SKILL.md | 112 ++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 skills/skill-check/SKILL.md diff --git a/skills/skill-check/SKILL.md b/skills/skill-check/SKILL.md new file mode 100644 index 00000000..767e9a52 --- /dev/null +++ b/skills/skill-check/SKILL.md @@ -0,0 +1,112 @@ +--- +name: skill-check +description: "Validate Claude Code skills against the agentskills specification. Catches structural, semantic, and naming issues before users do." +category: development +risk: safe +source: https://github.com/olgasafonova/SkillCheck-Free +date_added: "2026-03-11" +author: olgasafonova +tags: [validation, linter, agentskills, skill-authoring, code-quality] +tools: [claude, cursor, windsurf, codex-cli] +license: MIT +allowed-tools: Read Glob +compatibility: claude-code +--- + +# SkillCheck + +## Overview + +Validate SKILL.md files against the [agentskills specification](https://agentskills.io) and Anthropic best practices. Catches structural errors, semantic contradictions, naming anti-patterns, and quality gaps in a single read-only pass. + +## When to Use This Skill + +- Use when user says "check skill", "skillcheck", or "validate SKILL.md" +- Use when reviewing a skill before publishing to a marketplace +- Use when debugging why a skill doesn't trigger correctly +- Use when onboarding a team to skill authoring standards +- Do NOT use for anti-slop detection, security scanning, or token analysis; use [SkillCheck Pro](https://getskillcheck.com) for those + +## How It Works + +### Step 1: Parse + +Read the target SKILL.md file and extract YAML frontmatter. + +### Step 2: Validate + +Apply all Free tier checks in order: + +| Category | Checks | What it catches | +|----------|--------|----------------| +| Structure (1.x) | Name format, description WHAT+WHEN, allowed-tools, categories, XML injection | Malformed frontmatter, missing fields | +| Body (2.x) | Line count, hardcoded paths, stale dates, empty sections, deprecated syntax, MCP tool qualification | Content quality issues | +| Naming (3.x) | Vague terms, single-word names, gerund suggestions | Poor discoverability | +| Semantic (4.x) | Contradictions, ambiguous terms, missing output format, wisdom/platitudes, misplaced triggers | Logical inconsistencies | +| Quality (8.x) | Examples, error handling, triggers, output format, prerequisites, negative triggers | Strengths (positive patterns) | + +### Step 3: Score + +Calculate overall score (0-100). Penalties: critical = -20, warning = -5, suggestion = -1. + +### Step 4: Report + +Return structured results: score, grade (Excellent/Good/Needs Work/Poor), issue list with check IDs, line numbers, messages, and fix suggestions. + +## Examples + +### Example 1: Validating a skill + +``` +User: check my skill at ~/.claude/skills/weekly-report/SKILL.md + +SkillCheck output: +## weekly-report Check Results [FREE] + +Score: 85/100 (Good) + +### Warnings (2) + - 1.2-desc-when (line 3): Description missing WHEN clause + - 4.5-desc-no-triggers (line 3): Description lacks triggering conditions + +### Suggestions (1) + - 3.4-gerund-naming (line 2): Skill name could use gerund form + +### Passed Checks: 28 +``` + +### Example 2: Clean skill passes all checks + +``` +User: skillcheck ~/.claude/skills/processing-pdfs/SKILL.md + +Score: 100/100 (Excellent) +All 31 checks passed. No issues found. +``` + +## Limitations + +- Read-only: does not modify any files +- Free tier covers structural, semantic, and naming checks only +- Anti-slop, security, WCAG, token, enterprise, and workflow checks require [SkillCheck Pro](https://getskillcheck.com) +- Semantic checks (contradiction detection, wisdom/platitude) are heuristic with ~5% false positive rate +- Does not validate referenced files or scripts; only checks SKILL.md content +- Single-file validation; does not cross-check against other skills in the same directory + +## Best Practices + +- Run SkillCheck before submitting skills to any marketplace +- Fix all critical and warning issues; suggestions are optional +- Use the check ID (e.g., `1.2-desc-when`) to find the exact rule in the skill body +- Re-run after fixes to confirm the score improved + +## Common Pitfalls + +- **Problem:** Score seems low due to many suggestions + **Solution:** Suggestions cap at -15 points total. Focus on warnings and criticals first. + +- **Problem:** False positive on ambiguous terms inside code blocks + **Solution:** SkillCheck skips code blocks and inline code. If you still see false positives, wrap the term in backticks. + +- **Problem:** Wisdom/platitude check flags legitimate instructions + **Solution:** Rephrase generic advice ("Remember that testing is important") as concrete directives ("Run tests before committing").