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>

README.md

@@ -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