Find out why your Agent Skill isn't loading or never triggers, with the exact line and fix.
Find out why your Agent Skill isn't loading or never triggers. skill_lint.py checks every SKILL.md in a folder against the open Agent Skills spec (agentskills.io) and the extra rules of Claude Code, Cursor and Codex, and tells you the exact line and the fix.
Offline. Python 3.9+, no dependencies (it has its own small YAML frontmatter reader), no account, no network.
python3 tools/skill_lint.py examples/broken # see every check fire
python3 tools/skill_lint.py .claude/skills # or .cursor/skills, .agents/skills, a whole repo: .
python3 tools/skill_lint.py . --target cursor # only one agent's rules: spec | claude | cursor | codex | allExit 0 = no errors, 1 = errors (--strict also fails on warnings), 2 = no SKILL.md found. --json for CI, --quiet hides tips. A ready GitHub Actions workflow is in examples/github-workflow.yml.
| Area | Checks |
|---|---|
| Frontmatter | missing --- block, unclosed block, empty block, "must be a YAML mapping" (lists, stray text), unquoted : in a value ("mapping values are not allowed here"), tabs, duplicate keys, unterminated quotes |
| name | required (spec, Cursor, Codex; Claude Code falls back to the folder), 1-64 chars, lowercase/digits/single hyphens, must match the folder name |
| description | required, <= 1024 chars, too short, no "Use when ..." trigger, not front-loaded; Claude Code's 1,536-char cap on description + when_to_use |
| Spec fields | compatibility 1-500 chars, metadata string map (quote version: "1.0"), allowed-tools format and misplaced :*, unlimited Bash grants |
| Claude Code | booleans for disable-model-invocation / user-invocable / background, context: fork, agent without fork, shell, a skill nothing can invoke, $ARGUMENTS without argument-hint, typos like allowed_tools / when-to-use |
| Cursor | paths globs (empty, leading /, top-level-only *.ts) |
| Codex | agents/openai.yaml allow_implicit_invocation value |
| Body & files | empty body, > 500 lines or ~5,000 tokens, links to files that don't exist, references nested too deep, scripts with a shebang that aren't executable, hard-coded secrets, file not named exactly SKILL.md, duplicate skill names across the repo |
Checked against the Agent Skills specification, Claude Code skills docs, Cursor skills docs and Codex skills docs (November 2026).
Zip, 14 KB, v1.0, 14 files. Free to use, modify and share for any purpose, including commercial work, as long as this notice stays in copies. Not affiliated with Anthropic, Anysphere (Cursor) or OpenAI.
Free SKILL.md validator: fix 'frontmatter must be a YAML mapping', bad names, weak descriptions and broken references for Claude Code, Cursor and Codex skills.
21 tested Cursor Agent Skills (code review for Python/TS/Java, security, tests, PRs, migrations, releases), an installer and a commands-to-skills converter. $15.
View Cursor Skills Pack: 21 SKILL.md Workflow Skills + Commands-to-Skills ConverterTested Claude Code hooks as a plugin: block rm -rf and force-push to main, protect .env and lockfiles, catch API keys in files, audit log. $19 once.
View Claude Code Safety HooksFree Claude Code hooks examples: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification and Stop, plus a local tester that checks your hook's output.
View Claude Code Hooks Starter (Free)Short weekly digest of new x402 + MCP tools and free kits, including the MCP OAuth Checker. The download above works without signing up. No spam, unsubscribe any time.