# Validator

The validator checks a skill directory for correctness, completeness, and safety. It returns a validation result with a score, errors, and warnings.

---

## Usage

```bash
skilllane validate <path> [options]
```

| Option | Description |
|--------|-------------|
| `--strict` | Fail immediately if any required file is missing |
| `--json` | Output results as JSON |

---

## Scoring System

The validator starts at **100 points** and deducts points for issues found:

### Required Files (-15 each)

Each missing required file costs 15 points:

| File | Penalty |
|------|---------|
| `SKILL.md` | -15 |
| `metadata.json` | -15 |
| `tools.json` | -15 |
| `examples.md` | -15 |
| `eval.md` | -15 |

### metadata.json Checks

| Check | Penalty | Type |
|-------|---------|------|
| Invalid JSON | -15 | error |
| `name` not kebab-case | -10 | error |
| `version` not semver | -10 | error |
| Missing `name` field | -10 | error |
| Missing `version` field | -10 | error |
| Missing `title` field | -10 | error |
| Missing `description` field | -10 | error |
| Missing `targets` field | -10 | error |
| Empty `title` | -5 | error |
| Empty `description` | -5 | error |
| Empty `targets` | -5 | error |
| Empty `tags` | -3 | warning |

### tools.json Checks

| Check | Penalty | Type |
|-------|---------|------|
| Invalid JSON | -10 | error |
| No tools array | -10 | error |
| Empty tools array | -3 | warning |

### Content Checks

| Check | Penalty | Type |
|-------|---------|------|
| SKILL.md empty | -15 | error |
| SKILL.md < 50 chars | -5 | warning |
| examples.md empty | -10 | error |
| No example section header | -5 | warning |
| eval.md empty | -10 | error |
| No criteria section header | -5 | warning |

### File Size

| Check | Penalty | Type |
|-------|---------|------|
| File exceeds 1MB | -5 | warning |

### Secrets Detection

Scans all files for known secret patterns:

| Pattern | Example | Penalty |
|---------|---------|---------|
| AWS Access Key | `AKIA...` | -15 |
| AWS Secret Key | `aws_secret_access_key=...` | -15 |
| Private Key | `-----BEGIN RSA PRIVATE KEY-----` | -15 |
| Generic API Key | `api_key=...` | -15 |
| Password Assignment | `password=...` | -15 |
| Bearer Token | `bearer ...` | -15 |
| GitHub Token | `ghp_...` or `ghs_...` | -15 |
| Slack Token | `xoxb-...` | -15 |

---

## Score Interpretation

| Score | Rating | Description |
|-------|--------|-------------|
| 80-100 | Production-ready | Meets all or nearly all requirements |
| 50-79 | Usable | Has warnings or minor issues |
| 0-49 | Needs work | Missing required files or has errors |

---

## Output

### Human-readable

```
Validating: ./my-skill
  Files checked: 5

Skill: My Skill (my-skill v0.1.0)
  Category: engineering | Tags: debugging

  Score: 85/100

  Warnings (1):
    • metadata.tags is empty

✓ Skill is valid!
```

### JSON

```json
{
  "valid": true,
  "score": 85,
  "errors": [],
  "warnings": ["metadata.tags is empty"],
  "checkedFiles": ["SKILL.md", "metadata.json", "tools.json", "examples.md", "eval.md"],
  "metadata": {
    "name": "my-skill",
    "version": "0.1.0",
    "title": "My Skill",
    "description": "A skill",
    "category": "engineering",
    "targets": ["all"],
    "tags": [],
    "author": "unknown",
    "license": "MIT",
    "requiresTools": [],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}
```

---

## Strict Mode

With `--strict`, the validator returns immediately if any required file is missing, without checking file contents. Useful for CI pipelines:

```bash
skilllane validate ./my-skill --strict --json
```

---

## Programmatic Usage

```typescript
import { validateSkill } from '@talocode/skilllane';

const result = await validateSkill('./my-skill', { strict: false });

console.log(result.valid);    // true or false
console.log(result.score);    // 0-100
console.log(result.errors);   // string[]
console.log(result.warnings); // string[]
```