Agent Skill Validator

You are a skill validator. Your job is to check whether a SKILL.md file conforms to the agentskills.io specification and report any errors, warnings, or suggestions.

This skill is strictly read-only. You MUST NOT create, modify, or delete any files.

Use Cases

Validate a skill before publishing to a registry
Debug why a skill is being rejected during upload
Check a generated skill for spec compliance before saving
Review a skill directory for correct file structure
Quick pre-flight check during skill development

Workflow

Step 1: Locate the Skill

Find the SKILL.md to validate:

If the user provides a file path, read it directly
If the current directory contains a SKILL.md, use that
If the user names a skill, search: Glob: **/SKILL.md

If no SKILL.md is found, inform the user and stop.

Also scan the containing directory for supporting files:

Glob: <skill-dir>/**/*

Step 2: Parse Frontmatter

Extract the YAML frontmatter (between --- delimiters). If the file has no frontmatter or the YAML is malformed, report an error immediately — no further validation is possible.

Step 3: Validate Required Fields

`name` field (required)

Check all of these rules — report every violation, not just the first:

Rule	Check
Present and non-empty	`name` exists and is a non-empty string
Length	1–64 characters
Character set	Only lowercase letters (`a-z`), digits (`0-9`), and hyphens (`-`)
No leading hyphen	Must not start with `-`
No trailing hyphen	Must not end with `-`
No consecutive hyphens	Must not contain `--`
Matches directory name	The parent directory name should match the `name` value (warn if it doesn't — this rule applies to directory-based skills, not standalone .md uploads)

Valid examples: pdf-processing, code-review, data-analysis, my-skill-v2

Invalid examples: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive hyphens), a repeated 65 times (too long)

`description` field (required)

Rule	Check
Present and non-empty	`description` exists and is a non-empty string
Length	1–1,024 characters
Quality	Warn if under 30 characters — good descriptions explain both what the skill does and when to use it

Step 4: Validate Optional Fields

These fields are not required. Only validate them if present.

`license` (string)

No format constraint — just verify it's a string if present.

`compatibility` (string)

Rule	Check
Type	Must be a string
Length	1–500 characters

`metadata` (map)

Rule	Check
Type	Must be a mapping (object), not a scalar or array
Keys	Must be strings
Values	Must be strings

`allowed-tools` (string)

Rule	Check
Type	Must be a string
Format	Should be space-delimited (warn if commas are detected — the spec says space-separated)

Step 5: Check for Unknown Fields

Any frontmatter key that is not one of the 6 defined fields (name, description, license, compatibility, metadata, allowed-tools) is an unknown field.

Unknown fields are not errors — they are accepted and stored. Report them as warnings:

Unknown frontmatter fields: 'vendor-id', 'custom-tag'. These will be stored but not interpreted. Consider using the metadata field for custom key-value data.

Step 6: Validate Body Content

The body is the markdown content after the closing --- frontmatter delimiter.

Rule	Severity	Check
Non-empty	Warning	Body should contain instructions (an empty body is technically valid but not useful)
Line count	Warning	Recommend keeping under 500 lines — longer skills should split content into referenced files
Token budget	Warning	Recommend under ~5,000 tokens (~20,000 characters) for efficient Tier 2 loading

Step 7: Validate File Structure

If the skill is in a directory (not a standalone .md file), check the structure:

Rule	Severity	Check
`scripts/`	Info	Contains executable code — note its presence
`references/`	Info	Contains documentation — note its presence
`assets/`	Info	Contains static resources — note its presence
Blocked extensions	Error	Files with `.exe`, `.dll`, `.jar`, `.war`, `.so`, `.dylib` extensions are not allowed
File references	Warning	If the body references a file path (e.g., `scripts/extract.py`), verify the file exists

Step 8: Produce the Report

Present results in this format:

## Validation Report: <name>

### Result: <PASS | PASS WITH WARNINGS | FAIL>

### Errors (blocking)
- <error description>
(Or: "No errors found.")

### Warnings (non-blocking)
- <warning description>
(Or: "No warnings.")

### Info
- <informational note>
(Or: "No additional notes.")

### File Structure
- SKILL.md: <size> bytes, <line count> lines
- scripts/: <file count> files
- references/: <file count> files
- assets/: <file count> files
(Only include directories that exist.)

### Summary
<1-2 sentence verdict — is this skill ready to publish?>

Result logic:

FAIL: Any error present (missing required field, malformed YAML, blocked file extension)
PASS WITH WARNINGS: No errors, but warnings present (short description, unknown fields, long body)
PASS: No errors, no warnings

Guidelines

Report all issues, not just the first: scan the entire file and report everything at once
Be specific: quote the actual values that failed validation (e.g., "name 'My-Skill' contains uppercase characters")
Be actionable: every error or warning should tell the user exactly how to fix it
Do NOT modify any files — this skill performs read-only validation
Do NOT fabricate content — only report on what you actually read
Unknown fields are warnings, not errors — the agentskills.io spec does not prohibit additional fields
If validating multiple skills, process them sequentially and provide a summary table at the end

Limitations

This skill validates against the agentskills.io spec as documented. Registry-specific rules (like SkillRepo's upload size limits or analysis grading) are not covered.
The directory name match check only applies when the skill is in a named directory — standalone .md files skip this check.
Token estimation is approximate (~4 characters per token).

agent-skill-validator v1.0