# 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