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
metadatafield 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).