---
name: validate-skill
description: |
  Validate Agent Skills against the live agentskills.io specification.
  Fetches the latest spec dynamically - no CLI tools or dependencies required.
  Triggers: "validate skill", "check skill", "skill validation", "lint skill".
license: MIT
compatibility: Requires web fetch capability and file read access. Shell access optional (improves character counting accuracy).
metadata:
  author: KemingHe
  version: "1.0.0"
---

# Validate Skill

Validate an Agent Skill against the live [agentskills.io](https://agentskills.io) specification. Fetches the latest spec at runtime - always current, zero dependencies.

**Temporary persona**: Specification compliance reviewer.

## When to Use This Skill

- Before publishing or sharing a skill
- After editing SKILL.md frontmatter or structure
- Reviewing third-party skills for correctness
- Quick validation without installing CLI tools

## Process

### Step 1: Fetch the Live Specification

Fetch the Agent Skills specification from:

```plaintext
https://agentskills.io/specification
```

Use web fetch, browse, or curl to retrieve the full page content. Parse and retain all:

- Field names, required/optional status, and constraints
- Naming rules and regex patterns
- Structural requirements (directories, file references)
- Recommended limits (line count, token budget)

**This is the single source of truth.** Do not hardcode or assume rules - extract them from the fetched spec.

If the fetch fails, stop and report the error. Never validate against stale or assumed rules.

### Step 2: Read the Target Skill

Determine the target:

- If given a file path, read the SKILL.md directly
- If given a directory, look for SKILL.md at the root of that directory

Read the full file content. Note the parent directory name for name-matching validation.

### Step 3: Validate Frontmatter

Parse the YAML frontmatter (content between `---` delimiters). Validate each field against the constraints extracted in Step 1.

**Character counting**: When shell access is available, use `wc -m` for precise character counts:

```shell
printf '%s' "<field-value>" | wc -m
```

When shell is unavailable, count from the text content directly.

**Check in order**:

1. **Structure**: File starts with `---`, contains valid YAML, has closing `---`
2. **Required fields**: All required fields present and non-empty
3. **Field constraints**: Each field meets its type, length, and format requirements from the spec
4. **Name pattern**: Apply the naming rules from the spec (charset, no leading/trailing/consecutive hyphens)
5. **Name-directory match**: `name` field value equals the parent directory name

### Step 4: Validate Body Content

Check the Markdown body (everything after the closing `---` of frontmatter):

1. **Line count**: Count total lines in the file. Flag if over the spec's recommended limit.
2. **Progressive disclosure**: Essential instructions should be in SKILL.md; detailed references in separate files.
3. **File references**: If references to other files exist, verify paths are relative and one level deep.

### Step 5: Validate Directory Structure (if applicable)

If a directory path was provided (not just a file):

1. SKILL.md exists at the directory root
2. Optional directories follow the spec's naming conventions (e.g., `scripts/`, `references/`, `assets/`)
3. No deeply nested reference chains (advisory)

### Step 6: Report Findings

Present results in a structured validation report:

```markdown
## Validation Report: [skill-name]

**Spec fetched from**: https://agentskills.io/specification
**Target**: [path]
**Overall result**: PASS | FAIL | WARN

| # | Check | Status | Detail |
| :--- | :--- | :--- | :--- |
| 1 | Frontmatter YAML valid | PASS/FAIL | [detail] |
| 2 | `name` present | PASS/FAIL | [value or "missing"] |
| 3 | `name` format valid | PASS/FAIL | [detail] |
| 4 | `name` length | PASS/FAIL | [N chars, limit from spec] |
| 5 | `name`-directory match | PASS/FAIL/SKIP | [comparison or "no directory"] |
| 6 | `description` present | PASS/FAIL | [detail] |
| 7 | `description` length | PASS/FAIL | [N chars, limit from spec] |
| ... | [additional checks per spec] | ... | ... |
| N | Line count | PASS/WARN | [count vs recommended limit] |
```

**Status classification**:

- **FAIL**: Violates a required constraint from the spec
- **WARN**: Exceeds a recommended limit or missing a suggested element
- **PASS**: Meets the constraint
- **SKIP**: Check not applicable (e.g., no directory provided for name-directory match)

**Overall result**: FAIL if any check is FAIL. WARN if no FAILs but has WARNs. PASS otherwise.

## Constraints

- **Live spec only**: Always fetch the specification at runtime - never validate against assumed or memorized rules
- **Non-destructive**: Read-only operations only - never modify the target skill files
- **Precise counting**: Use `wc -m` for character counts when shell is available
- **Structured output**: Always use the report table format for findings
- **Single source of truth**: The fetched spec defines what is valid; this skill defines how to check it