Initial commit
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>
This commit is contained in:
Ethan Beard
15
.editorconfig
Normal file
15
.editorconfig
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
root = true
|
||||||
|
|
||||||
|
[*]
|
||||||
|
indent_style = space
|
||||||
|
indent_size = 2
|
||||||
|
end_of_line = lf
|
||||||
|
charset = utf-8
|
||||||
|
trim_trailing_whitespace = true
|
||||||
|
insert_final_newline = true
|
||||||
|
|
||||||
|
[*.md]
|
||||||
|
trim_trailing_whitespace = false
|
||||||
|
|
||||||
|
[Makefile]
|
||||||
|
indent_style = tab
|
||||||
8
.gitignore
vendored
Normal file
8
.gitignore
vendored
Normal file
@@ -0,0 +1,8 @@
|
|||||||
|
node_modules/
|
||||||
|
dist/
|
||||||
|
*.log
|
||||||
|
.DS_Store
|
||||||
|
.env
|
||||||
|
.claude/
|
||||||
|
coverage/
|
||||||
|
.nyc_output/
|
||||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2024
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
113
README.md
Normal file
113
README.md
Normal file
@@ -0,0 +1,113 @@
|
|||||||
|
# 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
|
||||||
196
package-lock.json
generated
Normal file
196
package-lock.json
generated
Normal file
@@ -0,0 +1,196 @@
|
|||||||
|
{
|
||||||
|
"name": "skill-md-validator",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"lockfileVersion": 3,
|
||||||
|
"requires": true,
|
||||||
|
"packages": {
|
||||||
|
"": {
|
||||||
|
"name": "skill-md-validator",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"commander": "^12.1.0",
|
||||||
|
"gray-matter": "^4.0.3",
|
||||||
|
"semver": "^7.6.3"
|
||||||
|
},
|
||||||
|
"bin": {
|
||||||
|
"skill-validate": "dist/index.js"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^20.14.0",
|
||||||
|
"@types/semver": "^7.5.8",
|
||||||
|
"typescript": "^5.5.0"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=18.0.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/@types/node": {
|
||||||
|
"version": "20.19.30",
|
||||||
|
"resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.30.tgz",
|
||||||
|
"integrity": "sha512-WJtwWJu7UdlvzEAUm484QNg5eAoq5QR08KDNx7g45Usrs2NtOPiX8ugDqmKdXkyL03rBqU5dYNYVQetEpBHq2g==",
|
||||||
|
"dev": true,
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"undici-types": "~6.21.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/@types/semver": {
|
||||||
|
"version": "7.7.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.7.1.tgz",
|
||||||
|
"integrity": "sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==",
|
||||||
|
"dev": true,
|
||||||
|
"license": "MIT"
|
||||||
|
},
|
||||||
|
"node_modules/argparse": {
|
||||||
|
"version": "1.0.10",
|
||||||
|
"resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
|
||||||
|
"integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"sprintf-js": "~1.0.2"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/commander": {
|
||||||
|
"version": "12.1.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
|
||||||
|
"integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=18"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/esprima": {
|
||||||
|
"version": "4.0.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
|
||||||
|
"integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
|
||||||
|
"license": "BSD-2-Clause",
|
||||||
|
"bin": {
|
||||||
|
"esparse": "bin/esparse.js",
|
||||||
|
"esvalidate": "bin/esvalidate.js"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=4"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/extend-shallow": {
|
||||||
|
"version": "2.0.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
|
||||||
|
"integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"is-extendable": "^0.1.0"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=0.10.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/gray-matter": {
|
||||||
|
"version": "4.0.3",
|
||||||
|
"resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz",
|
||||||
|
"integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"js-yaml": "^3.13.1",
|
||||||
|
"kind-of": "^6.0.2",
|
||||||
|
"section-matter": "^1.0.0",
|
||||||
|
"strip-bom-string": "^1.0.0"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=6.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/is-extendable": {
|
||||||
|
"version": "0.1.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
|
||||||
|
"integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==",
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=0.10.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/js-yaml": {
|
||||||
|
"version": "3.14.2",
|
||||||
|
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz",
|
||||||
|
"integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"argparse": "^1.0.7",
|
||||||
|
"esprima": "^4.0.0"
|
||||||
|
},
|
||||||
|
"bin": {
|
||||||
|
"js-yaml": "bin/js-yaml.js"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/kind-of": {
|
||||||
|
"version": "6.0.3",
|
||||||
|
"resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
|
||||||
|
"integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=0.10.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/section-matter": {
|
||||||
|
"version": "1.0.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
|
||||||
|
"integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"extend-shallow": "^2.0.1",
|
||||||
|
"kind-of": "^6.0.0"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=4"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/semver": {
|
||||||
|
"version": "7.7.3",
|
||||||
|
"resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
|
||||||
|
"integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==",
|
||||||
|
"license": "ISC",
|
||||||
|
"bin": {
|
||||||
|
"semver": "bin/semver.js"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=10"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/sprintf-js": {
|
||||||
|
"version": "1.0.3",
|
||||||
|
"resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
|
||||||
|
"integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==",
|
||||||
|
"license": "BSD-3-Clause"
|
||||||
|
},
|
||||||
|
"node_modules/strip-bom-string": {
|
||||||
|
"version": "1.0.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
|
||||||
|
"integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==",
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=0.10.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/typescript": {
|
||||||
|
"version": "5.9.3",
|
||||||
|
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
|
||||||
|
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
|
||||||
|
"dev": true,
|
||||||
|
"license": "Apache-2.0",
|
||||||
|
"bin": {
|
||||||
|
"tsc": "bin/tsc",
|
||||||
|
"tsserver": "bin/tsserver"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=14.17"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/undici-types": {
|
||||||
|
"version": "6.21.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
|
||||||
|
"integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
|
||||||
|
"dev": true,
|
||||||
|
"license": "MIT"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
45
package.json
Normal file
45
package.json
Normal file
@@ -0,0 +1,45 @@
|
|||||||
|
{
|
||||||
|
"name": "skill-md-validator",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Validate skill.md files against the agent skill specification",
|
||||||
|
"main": "dist/index.js",
|
||||||
|
"bin": {
|
||||||
|
"skill-validate": "dist/index.js"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"build": "tsc",
|
||||||
|
"start": "node dist/index.js",
|
||||||
|
"dev": "tsc && node dist/index.js",
|
||||||
|
"prepublishOnly": "npm run build"
|
||||||
|
},
|
||||||
|
"keywords": [
|
||||||
|
"skill",
|
||||||
|
"markdown",
|
||||||
|
"validator",
|
||||||
|
"agent",
|
||||||
|
"ai"
|
||||||
|
],
|
||||||
|
"author": "",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"commander": "^12.1.0",
|
||||||
|
"gray-matter": "^4.0.3",
|
||||||
|
"semver": "^7.6.3"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^20.14.0",
|
||||||
|
"@types/semver": "^7.5.8",
|
||||||
|
"typescript": "^5.5.0"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=18.0.0"
|
||||||
|
},
|
||||||
|
"files": [
|
||||||
|
"dist"
|
||||||
|
],
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "https://github.com/severith/skill-md-validator.git"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/severith/skill-md-validator"
|
||||||
|
}
|
||||||
41
skill.md
Normal file
41
skill.md
Normal file
@@ -0,0 +1,41 @@
|
|||||||
|
---
|
||||||
|
name: skill-md-validator
|
||||||
|
version: 1.0.0
|
||||||
|
description: Validate skill.md files against the agent skill specification
|
||||||
|
homepage: https://github.com/severith/skill-md-validator
|
||||||
|
repository: https://github.com/severith/skill-md-validator.git
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
emoji: ✅
|
||||||
|
category: tooling
|
||||||
|
---
|
||||||
|
|
||||||
|
# skill-md-validator
|
||||||
|
|
||||||
|
Validate your skill.md files before publishing.
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install -g skill-md-validator
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Local file
|
||||||
|
skill-validate ./skill.md
|
||||||
|
|
||||||
|
# Remote URL
|
||||||
|
skill-validate https://example.com/skill.md
|
||||||
|
|
||||||
|
# Strict mode (warnings become errors)
|
||||||
|
skill-validate --strict ./skill.md
|
||||||
|
|
||||||
|
# JSON output
|
||||||
|
skill-validate --json ./skill.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Why
|
||||||
|
|
||||||
|
skill.md files are how agents discover and understand capabilities. A malformed file means agents can't find you or misunderstand what you offer. Validate before you ship.
|
||||||
23
src/fetcher.ts
Normal file
23
src/fetcher.ts
Normal file
@@ -0,0 +1,23 @@
|
|||||||
|
export async function fetchSkillContent(url: string): Promise<string> {
|
||||||
|
const response = await fetch(url, {
|
||||||
|
headers: {
|
||||||
|
'Accept': 'text/plain, text/markdown, */*',
|
||||||
|
'User-Agent': 'skill-md-validator/1.0.0',
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!response.ok) {
|
||||||
|
throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
return response.text();
|
||||||
|
}
|
||||||
|
|
||||||
|
export function isUrl(input: string): boolean {
|
||||||
|
try {
|
||||||
|
const url = new URL(input);
|
||||||
|
return url.protocol === 'http:' || url.protocol === 'https:';
|
||||||
|
} catch {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
81
src/index.ts
Normal file
81
src/index.ts
Normal file
@@ -0,0 +1,81 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
import { Command } from 'commander';
|
||||||
|
import { validateSkillInput } from './validator.js';
|
||||||
|
import { ValidationResult } from './types.js';
|
||||||
|
|
||||||
|
const program = new Command();
|
||||||
|
|
||||||
|
program
|
||||||
|
.name('skill-validate')
|
||||||
|
.description('Validate skill.md files against the agent skill specification')
|
||||||
|
.version('1.0.0')
|
||||||
|
.argument('<file>', 'Path to skill.md file or URL')
|
||||||
|
.option('-s, --strict', 'Treat warnings as errors')
|
||||||
|
.option('-j, --json', 'Output results as JSON')
|
||||||
|
.action(async (file: string, options: { strict?: boolean; json?: boolean }) => {
|
||||||
|
const result = await validateSkillInput(file, { strict: options.strict });
|
||||||
|
|
||||||
|
// In strict mode, warnings become errors
|
||||||
|
if (options.strict && result.warnings.length > 0) {
|
||||||
|
result.errors.push(...result.warnings);
|
||||||
|
result.warnings = [];
|
||||||
|
result.valid = result.errors.length === 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (options.json) {
|
||||||
|
outputJson(result);
|
||||||
|
} else {
|
||||||
|
outputHuman(result);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Exit codes: 0 = valid, 1 = invalid, 2 = file not found/fetch failed
|
||||||
|
if (!result.valid) {
|
||||||
|
const isFetchOrFileError = result.errors.some(
|
||||||
|
(e) => e.code === 'file-not-found' || e.code === 'fetch-failed'
|
||||||
|
);
|
||||||
|
process.exit(isFetchOrFileError ? 2 : 1);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
function outputJson(result: ValidationResult): void {
|
||||||
|
console.log(JSON.stringify(result, null, 2));
|
||||||
|
}
|
||||||
|
|
||||||
|
function outputHuman(result: ValidationResult): void {
|
||||||
|
if (result.valid) {
|
||||||
|
console.log(`✓ ${result.file} is valid\n`);
|
||||||
|
} else {
|
||||||
|
console.log(`✗ ${result.file} is invalid\n`);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (result.parsed) {
|
||||||
|
console.log(` name: ${result.parsed.name}`);
|
||||||
|
console.log(` version: ${result.parsed.version}`);
|
||||||
|
console.log(` description: ${truncate(result.parsed.description, 50)}`);
|
||||||
|
console.log();
|
||||||
|
}
|
||||||
|
|
||||||
|
if (result.errors.length > 0) {
|
||||||
|
console.log(' Errors:');
|
||||||
|
for (const error of result.errors) {
|
||||||
|
console.log(` ✗ ${error.message}`);
|
||||||
|
}
|
||||||
|
console.log();
|
||||||
|
}
|
||||||
|
|
||||||
|
if (result.warnings.length > 0) {
|
||||||
|
console.log(' Warnings:');
|
||||||
|
for (const warning of result.warnings) {
|
||||||
|
console.log(` ⚠ ${warning.message}`);
|
||||||
|
}
|
||||||
|
console.log();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function truncate(str: string, maxLength: number): string {
|
||||||
|
if (str.length <= maxLength) return str;
|
||||||
|
return str.slice(0, maxLength - 3) + '...';
|
||||||
|
}
|
||||||
|
|
||||||
|
program.parse();
|
||||||
191
src/rules.ts
Normal file
191
src/rules.ts
Normal file
@@ -0,0 +1,191 @@
|
|||||||
|
import * as semver from 'semver';
|
||||||
|
import { ValidationIssue, SkillMetadata } from './types.js';
|
||||||
|
|
||||||
|
const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
|
||||||
|
const MIN_DESCRIPTION_LENGTH = 10;
|
||||||
|
const MAX_DESCRIPTION_LENGTH = 200;
|
||||||
|
const WARN_DESCRIPTION_LENGTH = 100;
|
||||||
|
|
||||||
|
export function validateName(data: Record<string, unknown>): ValidationIssue | null {
|
||||||
|
if (!data.name) {
|
||||||
|
return { code: 'missing-name', message: "Missing required field 'name'" };
|
||||||
|
}
|
||||||
|
if (typeof data.name !== 'string') {
|
||||||
|
return { code: 'invalid-name', message: "'name' must be a string" };
|
||||||
|
}
|
||||||
|
if (!NAME_PATTERN.test(data.name)) {
|
||||||
|
return {
|
||||||
|
code: 'invalid-name-format',
|
||||||
|
message: "'name' must be lowercase alphanumeric with hyphens (e.g., 'my-skill')",
|
||||||
|
};
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateVersion(data: Record<string, unknown>): ValidationIssue | null {
|
||||||
|
if (!data.version) {
|
||||||
|
return { code: 'missing-version', message: "Missing required field 'version'" };
|
||||||
|
}
|
||||||
|
if (typeof data.version !== 'string') {
|
||||||
|
return { code: 'invalid-version', message: "'version' must be a string" };
|
||||||
|
}
|
||||||
|
if (!semver.valid(data.version)) {
|
||||||
|
return {
|
||||||
|
code: 'invalid-version-format',
|
||||||
|
message: `'version' must be valid semver (e.g., '1.0.0'), got '${data.version}'`,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateDescription(data: Record<string, unknown>): {
|
||||||
|
error: ValidationIssue | null;
|
||||||
|
warning: ValidationIssue | null;
|
||||||
|
} {
|
||||||
|
if (!data.description) {
|
||||||
|
return {
|
||||||
|
error: { code: 'missing-description', message: "Missing required field 'description'" },
|
||||||
|
warning: null,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
if (typeof data.description !== 'string') {
|
||||||
|
return {
|
||||||
|
error: { code: 'invalid-description', message: "'description' must be a string" },
|
||||||
|
warning: null,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
if (data.description.length < MIN_DESCRIPTION_LENGTH) {
|
||||||
|
return {
|
||||||
|
error: {
|
||||||
|
code: 'description-too-short',
|
||||||
|
message: `'description' must be at least ${MIN_DESCRIPTION_LENGTH} characters`,
|
||||||
|
},
|
||||||
|
warning: null,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
if (data.description.length > MAX_DESCRIPTION_LENGTH) {
|
||||||
|
return {
|
||||||
|
error: {
|
||||||
|
code: 'description-too-long',
|
||||||
|
message: `'description' must be at most ${MAX_DESCRIPTION_LENGTH} characters`,
|
||||||
|
},
|
||||||
|
warning: null,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
if (data.description.length > WARN_DESCRIPTION_LENGTH) {
|
||||||
|
return {
|
||||||
|
error: null,
|
||||||
|
warning: {
|
||||||
|
code: 'description-truncation-risk',
|
||||||
|
message: `'description' over ${WARN_DESCRIPTION_LENGTH} chars may be truncated in some displays`,
|
||||||
|
},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
return { error: null, warning: null };
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateUrl(value: unknown, field: string): ValidationIssue | null {
|
||||||
|
if (value === undefined) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
if (typeof value !== 'string') {
|
||||||
|
return { code: `invalid-${field}`, message: `'${field}' must be a string` };
|
||||||
|
}
|
||||||
|
try {
|
||||||
|
new URL(value);
|
||||||
|
return null;
|
||||||
|
} catch {
|
||||||
|
return { code: `invalid-${field}-url`, message: `'${field}' must be a valid URL` };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateHomepage(data: Record<string, unknown>): {
|
||||||
|
error: ValidationIssue | null;
|
||||||
|
warning: ValidationIssue | null;
|
||||||
|
} {
|
||||||
|
const error = validateUrl(data.homepage, 'homepage');
|
||||||
|
if (error) {
|
||||||
|
return { error, warning: null };
|
||||||
|
}
|
||||||
|
if (!data.homepage) {
|
||||||
|
return {
|
||||||
|
error: null,
|
||||||
|
warning: { code: 'missing-homepage', message: "Missing 'homepage' field" },
|
||||||
|
};
|
||||||
|
}
|
||||||
|
return { error: null, warning: null };
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateRepository(data: Record<string, unknown>): {
|
||||||
|
error: ValidationIssue | null;
|
||||||
|
warning: ValidationIssue | null;
|
||||||
|
} {
|
||||||
|
const error = validateUrl(data.repository, 'repository');
|
||||||
|
if (error) {
|
||||||
|
return { error, warning: null };
|
||||||
|
}
|
||||||
|
if (!data.repository) {
|
||||||
|
return {
|
||||||
|
error: null,
|
||||||
|
warning: { code: 'missing-repository', message: "Missing 'repository' field" },
|
||||||
|
};
|
||||||
|
}
|
||||||
|
return { error: null, warning: null };
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateApiBase(data: Record<string, unknown>): ValidationIssue | null {
|
||||||
|
const metadata = data.metadata as Record<string, unknown> | undefined;
|
||||||
|
if (!metadata?.api_base) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
return validateUrl(metadata.api_base, 'metadata.api_base');
|
||||||
|
}
|
||||||
|
|
||||||
|
export function validateContent(content: string): {
|
||||||
|
errors: ValidationIssue[];
|
||||||
|
warnings: ValidationIssue[];
|
||||||
|
} {
|
||||||
|
const errors: ValidationIssue[] = [];
|
||||||
|
const warnings: ValidationIssue[] = [];
|
||||||
|
|
||||||
|
const trimmed = content.trim();
|
||||||
|
if (!trimmed) {
|
||||||
|
errors.push({ code: 'empty-content', message: 'Body content after frontmatter is empty' });
|
||||||
|
return { errors, warnings };
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!/^#+\s+.+/m.test(content)) {
|
||||||
|
warnings.push({ code: 'no-heading', message: 'No markdown heading found in body' });
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!/```[\s\S]*?```/.test(content)) {
|
||||||
|
warnings.push({ code: 'no-code-examples', message: 'No code examples found in body' });
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!/^##\s+(Install|Installation)/im.test(content)) {
|
||||||
|
warnings.push({ code: 'no-install-section', message: 'No "## Install" section found' });
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!/^##\s+Usage/im.test(content)) {
|
||||||
|
warnings.push({ code: 'no-usage-section', message: 'No "## Usage" section found' });
|
||||||
|
}
|
||||||
|
|
||||||
|
return { errors, warnings };
|
||||||
|
}
|
||||||
|
|
||||||
|
export function extractMetadata(data: Record<string, unknown>): SkillMetadata | null {
|
||||||
|
if (!data.name || !data.version || !data.description) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
return {
|
||||||
|
name: data.name as string,
|
||||||
|
version: data.version as string,
|
||||||
|
description: data.description as string,
|
||||||
|
homepage: data.homepage as string | undefined,
|
||||||
|
repository: data.repository as string | undefined,
|
||||||
|
author: data.author as string | undefined,
|
||||||
|
license: data.license as string | undefined,
|
||||||
|
metadata: data.metadata as Record<string, unknown> | undefined,
|
||||||
|
};
|
||||||
|
}
|
||||||
28
src/types.ts
Normal file
28
src/types.ts
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
export interface ValidationIssue {
|
||||||
|
code: string;
|
||||||
|
message: string;
|
||||||
|
line?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface SkillMetadata {
|
||||||
|
name: string;
|
||||||
|
version: string;
|
||||||
|
description: string;
|
||||||
|
homepage?: string;
|
||||||
|
repository?: string;
|
||||||
|
author?: string;
|
||||||
|
license?: string;
|
||||||
|
metadata?: Record<string, unknown>;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ValidationResult {
|
||||||
|
valid: boolean;
|
||||||
|
file: string;
|
||||||
|
errors: ValidationIssue[];
|
||||||
|
warnings: ValidationIssue[];
|
||||||
|
parsed: SkillMetadata | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ValidatorOptions {
|
||||||
|
strict?: boolean;
|
||||||
|
}
|
||||||
139
src/validator.ts
Normal file
139
src/validator.ts
Normal file
@@ -0,0 +1,139 @@
|
|||||||
|
import matter from 'gray-matter';
|
||||||
|
import { ValidationResult, ValidationIssue, ValidatorOptions } from './types.js';
|
||||||
|
import {
|
||||||
|
validateName,
|
||||||
|
validateVersion,
|
||||||
|
validateDescription,
|
||||||
|
validateHomepage,
|
||||||
|
validateRepository,
|
||||||
|
validateApiBase,
|
||||||
|
validateContent,
|
||||||
|
extractMetadata,
|
||||||
|
} from './rules.js';
|
||||||
|
import { fetchSkillContent, isUrl } from './fetcher.js';
|
||||||
|
import * as fs from 'fs';
|
||||||
|
import * as path from 'path';
|
||||||
|
|
||||||
|
export function validateSkill(
|
||||||
|
content: string,
|
||||||
|
filename: string,
|
||||||
|
_options: ValidatorOptions = {}
|
||||||
|
): ValidationResult {
|
||||||
|
const errors: ValidationIssue[] = [];
|
||||||
|
const warnings: ValidationIssue[] = [];
|
||||||
|
|
||||||
|
// Check for frontmatter markers
|
||||||
|
if (!content.startsWith('---')) {
|
||||||
|
errors.push({
|
||||||
|
code: 'missing-frontmatter',
|
||||||
|
message: 'File must start with YAML frontmatter (---)',
|
||||||
|
});
|
||||||
|
return { valid: false, file: filename, errors, warnings, parsed: null };
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parse frontmatter
|
||||||
|
let parsed: matter.GrayMatterFile<string>;
|
||||||
|
try {
|
||||||
|
parsed = matter(content);
|
||||||
|
} catch (err) {
|
||||||
|
errors.push({
|
||||||
|
code: 'invalid-frontmatter',
|
||||||
|
message: `Failed to parse frontmatter: ${err instanceof Error ? err.message : 'Unknown error'}`,
|
||||||
|
});
|
||||||
|
return { valid: false, file: filename, errors, warnings, parsed: null };
|
||||||
|
}
|
||||||
|
|
||||||
|
const data = parsed.data as Record<string, unknown>;
|
||||||
|
|
||||||
|
// Validate required fields
|
||||||
|
const nameError = validateName(data);
|
||||||
|
if (nameError) errors.push(nameError);
|
||||||
|
|
||||||
|
const versionError = validateVersion(data);
|
||||||
|
if (versionError) errors.push(versionError);
|
||||||
|
|
||||||
|
const descResult = validateDescription(data);
|
||||||
|
if (descResult.error) errors.push(descResult.error);
|
||||||
|
if (descResult.warning) warnings.push(descResult.warning);
|
||||||
|
|
||||||
|
// Validate optional URL fields
|
||||||
|
const homepageResult = validateHomepage(data);
|
||||||
|
if (homepageResult.error) errors.push(homepageResult.error);
|
||||||
|
if (homepageResult.warning) warnings.push(homepageResult.warning);
|
||||||
|
|
||||||
|
const repoResult = validateRepository(data);
|
||||||
|
if (repoResult.error) errors.push(repoResult.error);
|
||||||
|
if (repoResult.warning) warnings.push(repoResult.warning);
|
||||||
|
|
||||||
|
const apiBaseError = validateApiBase(data);
|
||||||
|
if (apiBaseError) errors.push(apiBaseError);
|
||||||
|
|
||||||
|
// Validate content body
|
||||||
|
const contentResult = validateContent(parsed.content);
|
||||||
|
errors.push(...contentResult.errors);
|
||||||
|
warnings.push(...contentResult.warnings);
|
||||||
|
|
||||||
|
// Extract metadata for result
|
||||||
|
const metadata = extractMetadata(data);
|
||||||
|
|
||||||
|
return {
|
||||||
|
valid: errors.length === 0,
|
||||||
|
file: filename,
|
||||||
|
errors,
|
||||||
|
warnings,
|
||||||
|
parsed: metadata,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function validateSkillFile(
|
||||||
|
filepath: string,
|
||||||
|
options: ValidatorOptions = {}
|
||||||
|
): Promise<ValidationResult> {
|
||||||
|
const absolutePath = path.resolve(filepath);
|
||||||
|
|
||||||
|
if (!fs.existsSync(absolutePath)) {
|
||||||
|
return {
|
||||||
|
valid: false,
|
||||||
|
file: filepath,
|
||||||
|
errors: [{ code: 'file-not-found', message: `File not found: ${filepath}` }],
|
||||||
|
warnings: [],
|
||||||
|
parsed: null,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
const content = fs.readFileSync(absolutePath, 'utf-8');
|
||||||
|
return validateSkill(content, filepath, options);
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function validateSkillUrl(
|
||||||
|
url: string,
|
||||||
|
options: ValidatorOptions = {}
|
||||||
|
): Promise<ValidationResult> {
|
||||||
|
try {
|
||||||
|
const content = await fetchSkillContent(url);
|
||||||
|
return validateSkill(content, url, options);
|
||||||
|
} catch (err) {
|
||||||
|
return {
|
||||||
|
valid: false,
|
||||||
|
file: url,
|
||||||
|
errors: [
|
||||||
|
{
|
||||||
|
code: 'fetch-failed',
|
||||||
|
message: err instanceof Error ? err.message : 'Failed to fetch URL',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
warnings: [],
|
||||||
|
parsed: null,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function validateSkillInput(
|
||||||
|
input: string,
|
||||||
|
options: ValidatorOptions = {}
|
||||||
|
): Promise<ValidationResult> {
|
||||||
|
if (isUrl(input)) {
|
||||||
|
return validateSkillUrl(input, options);
|
||||||
|
}
|
||||||
|
return validateSkillFile(input, options);
|
||||||
|
}
|
||||||
19
tsconfig.json
Normal file
19
tsconfig.json
Normal file
@@ -0,0 +1,19 @@
|
|||||||
|
{
|
||||||
|
"compilerOptions": {
|
||||||
|
"target": "ES2022",
|
||||||
|
"module": "commonjs",
|
||||||
|
"lib": ["ES2022"],
|
||||||
|
"outDir": "./dist",
|
||||||
|
"rootDir": "./src",
|
||||||
|
"strict": true,
|
||||||
|
"esModuleInterop": true,
|
||||||
|
"skipLibCheck": true,
|
||||||
|
"forceConsistentCasingInFileNames": true,
|
||||||
|
"resolveJsonModule": true,
|
||||||
|
"declaration": true,
|
||||||
|
"declarationMap": true,
|
||||||
|
"sourceMap": true
|
||||||
|
},
|
||||||
|
"include": ["src/**/*"],
|
||||||
|
"exclude": ["node_modules", "dist"]
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user