AGENT SKILL

skill-check

Validate Claude Code skills against the agentskills specification. Catches structural, semantic, and naming issues before users do.

License 许可
MIT
最近更新
2026-05-11
Stars
★ 3
Forks
1

01 前言 Front Matter

name
skill-check
risk
safe
tags
[ "validation", "linter", "agentskills", "skill-authoring", "code-quality" ]
tools
[ "claude", "cursor", "windsurf", "codex-cli" ]
author
olgasafonova
source
https://github.com/olgasafonova/SkillCheck-Free
license
MIT
category
development
date_added
2026-03-11
description
Validate Claude Code skills against the agentskills specification. Catches structural, semantic, and naming issues before users do.
allowed-tools
Read Glob
compatibility
claude-code

03 SKILL.md 正文

SkillCheck

Overview

Validate SKILL.md files against the agentskills specification 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 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
  • 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").

04 同仓库更多 Skills

qhjqhj00
qhjqhj00/research-skills-pool

transformer-lens-interpretability

Provides guidance for mechanistic interpretability research using TransformerLens to inspect and manipulate transformer internals via HookPoints and activation caching. Use when reverse-engineering model algorithms, studying attention patterns, or performing activation patching experiments.

★ 3
qhjqhj00
qhjqhj00/research-skills-pool

wiki-vitepress

Packages generated wiki Markdown into a VitePress static site with dark theme, dark-mode Mermaid diagrams with click-to-zoom, and production build output. Use when the user wants to create a browsable website from generated wiki pages.

★ 3
qhjqhj00
qhjqhj00/research-skills-pool

phoenix-observability

Open-source AI observability platform for LLM tracing, evaluation, and monitoring. Use when debugging LLM applications with detailed traces, running evaluations on datasets, or monitoring production AI systems with real-time insights.

★ 3
qhjqhj00
qhjqhj00/research-skills-pool

frontend-ui-dark-ts

Build dark-themed React applications using Tailwind CSS with custom theming, glassmorphism effects, and Framer Motion animations. Use when creating dashboards, admin panels, or data-rich interfaces with a refined dark aesthetic.

★ 3
qhjqhj00
qhjqhj00/research-skills-pool

tensorboard

Visualize training metrics, debug models with histograms, compare experiments, visualize model graphs, and profile performance with TensorBoard - Google's ML visualization toolkit

★ 3
qhjqhj00
qhjqhj00/research-skills-pool

markdown-mermaid-writing

Comprehensive markdown and Mermaid diagram writing skill. Use when creating any scientific document, report, analysis, or visualization. Establishes text-based diagrams as the default documentation standard with full style guides (markdown + mermaid), 24 diagram type references, and 9 document templates.

★ 3