67af4e2125
CLI tool to validate skill.md files against the agent skill specification. Supports local files and remote URLs, with human-readable and JSON output. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
114 lines
2.3 KiB
Markdown
114 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
npm install -g skill-md-validator
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build
|
|
npm run build
|
|
|
|
# Run locally
|
|
npm start ./skill.md
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|