Validate Agent Skills YAML, field types, naming, lengths, and discovery layout. Use when authoring, reviewing, or checking SKILL.md files. Requires PyYAML; uv runs it in an isolated environment.
Installs into .claude/skills of the current project.
Are you the author of Skill Spec Lint?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/fakoli-skill-spec-lint)
---
name: skill-spec-lint
description: Validate Agent Skills YAML, field types, naming, lengths, and discovery layout. Use when authoring, reviewing, or checking SKILL.md files. Requires PyYAML; uv runs it in an isolated environment.
---
# Skill Spec Lint
Resolve the plugin root from the loaded skill (`../..`) or the host's plugin-root variable, then run:
```bash
uv run --script "<plugin-root>/scripts/skill_spec_lint.py" [PATH ...]
```
Inputs may be `SKILL.md`, a skill directory, a plugin, or a repository. Overlapping paths are counted once. `--help` shows the CLI. With no paths, scan the current directory.
The linter parses complete YAML, rejects duplicate keys, and validates name/directory agreement, required strings, optional types, string metadata, and length bounds. A missing YAML dependency is an error, never a reduced-coverage pass. `uv` may download PyYAML on first use; validation itself is local. If PyYAML is already installed, direct Python invocation also works.
Errors return 1; CLI/dependency errors return 2. Unknown host extensions, nested discovery layout, and the recommended 500-line body budget are warnings. Warnings do not fail the run. Discovery layout is a repository convention, not a universal host guarantee.
Report concrete findings. This validates structure, not whether a skill activates appropriately or supports good decisions. See [README](../../README.md) and the [Agent Skills specification](https://agentskills.io/specification).
