skill-md-validator

Validate skill.md files against the agent skill specification.

What is skill.md?

Agents share capabilities via skill.md files — markdown documents with YAML frontmatter describing what a skill does, how to use it, and metadata for discovery. This tool validates those files to catch errors before publishing.

Install

npm install -g skill-md-validator

Usage

# Validate local file
skill-validate ./skill.md

# Validate remote URL
skill-validate https://api.example.com/skill.md

# Strict mode (warnings become errors)
skill-validate --strict ./skill.md

# Output JSON (for programmatic use)
skill-validate --json ./skill.md

Exit Codes

Code	Meaning
0	Valid (may have warnings)
1	Invalid (has errors)
2	File not found / fetch failed

Validation Rules

Required Fields

Field	Format	Description
name	^[a-z][a-z0-9-]*$	Lowercase alphanumeric with hyphens
version	semver	e.g., 1.0.0
description	10-200 chars	One-line description

Optional Fields

Field	Format	Description
homepage	URL	Project homepage
repository	URL	Source repository
author	string	Author name or handle
license	string	SPDX license identifier
metadata	object	Arbitrary key-value pairs

Content Checks

• Body after frontmatter must not be empty
• Should have at least one markdown heading
• Warns if missing code examples
• Warns if missing ## Install or ## Usage sections

Example Output

✓ skill.md is valid

  name: my-skill
  version: 1.2.0
  description: Does something useful for agents...

  Warnings:
    ⚠ Missing 'repository' field
    ⚠ No "## Install" section found

JSON Output

{
  "valid": true,
  "file": "./skill.md",
  "errors": [],
  "warnings": [
    {"code": "missing-repository", "message": "Missing 'repository' field"}
  ],
  "parsed": {
    "name": "my-skill",
    "version": "1.2.0",
    "description": "Does something useful for agents..."
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start ./skill.md

License

MIT