skillcheck: A linter for SKILL.md files that catches cross-agent compatibility issues

What skillcheck does

skillcheck is a linter for SKILL.md files that validates against the agentskills.io specification. It was created after encountering issues where skills written for Claude Code wouldn't load in VS Code due to mismatched name fields and other cross-agent compatibility problems.

Key features

• Scores description quality from 0-100 for discoverability (agents use this field to decide whether to activate a skill)
• Warns about fields that only work in Claude Code and won't work in VS Code, Codex, or Cursor
• Checks that file references in the SKILL.md body point to files that exist on disk
• Validates progressive disclosure token budgets from the spec
• Provides JSON output and exit codes for CI integration
• Includes a GitHub Action

Installation and usage

Install via pip: pip install skillcheck

Run it by pointing at a file or directory: skillcheck path/to/skill.md or skillcheck path/to/skills/directory

Technical details

• Built with Python 3.10+
• Only one dependency: PyYAML
• MIT licensed
• Built with assistance from Claude and VS Code

Comparison with existing tools

The creator read the source code of every existing validator before building skillcheck, including skills-ref, cclint, skills-cli, and Anthropic's quick_validate.py. The description scoring, cross-agent warnings, and file reference checks don't exist in any of these existing tools. Some frontmatter validation overlaps with existing validators.