Review Skill Format

Validate a SKILL.md file against the agentskills.io open standard. This skill checks YAML frontmatter completeness, required section presence, procedure step format (Expected/On failure blocks), line count limits, and registry synchronization. Use this before merging any new or modified skill.

When to Use

A new skill has been authored and needs format validation before merge
An existing skill has been modified and needs re-validation
Performing a batch audit of all skills in a domain
Verifying a skill created by the create-skill meta-skill
Reviewing a contributor's skill submission in a pull request

Inputs

Required: Path to the SKILL.md file (e.g., skills/setup-vault/SKILL.md)
Optional: Strictness level (lenient or strict, default: strict)
Optional: Whether to check registry sync (default: yes)

Procedure

Step 1: Verify File Exists and Read Content

Confirm the SKILL.md file exists at the expected path and read its full content.

# Verify file exists
test -f skills/<skill-name>/SKILL.md && echo "EXISTS" || echo "MISSING"

# Count lines
wc -l < skills/<skill-name>/SKILL.md

Expected: File exists and content is readable. Line count is displayed.

On failure: If the file does not exist, check the path for typos. Verify the skill directory exists with ls skills/<skill-name>/. If the directory is missing, the skill has not been created yet — use create-skill first.

Step 2: Check YAML Frontmatter Fields

Parse the YAML frontmatter block (between --- delimiters) and verify all required and recommended fields are present.

Required fields:

name — matches directory name (kebab-case)
description — under 1024 characters, starts with a verb
license — typically MIT
allowed-tools — comma-separated or space-separated tool list

Recommended metadata fields:

metadata.author — author name
metadata.version — semantic version string
metadata.domain — one of the domains listed in skills/_registry.yml
metadata.complexity — one of: basic, intermediate, advanced
metadata.language — primary language or multi
metadata.tags — comma-separated, 3-6 tags, includes domain name

# Check required frontmatter fields exist
head -30 skills/<skill-name>/SKILL.md | grep -q '^name:' && echo "name: OK" || echo "name: MISSING"
head -30 skills/<skill-name>/SKILL.md | grep -q '^description:' && echo "description: OK" || echo "description: MISSING"
head -30 skills/<skill-name>/SKILL.md | grep -q '^license:' && echo "license: OK" || echo "license: MISSING"
head -30 skills/<skill-name>/SKILL.md | grep -q '^allowed-tools:' && echo "allowed-tools: OK" || echo "allowed-tools: MISSING"

Expected: All four required fields present. All six metadata fields present. name matches directory name. description is under 1024 characters.

On failure: Report each missing field as BLOCKING. If name does not match directory name, report as BLOCKING with the expected value. If description exceeds 1024 characters, report as SUGGEST with current length.

Step 3: Check Required Sections

Verify all six required sections are present in the skill body (after frontmatter).

Required sections:

## When to Use
## Inputs
## Procedure (with ### Step N: sub-sections)
## Validation (may also appear as ## Validation Checklist)
## Common Pitfalls
## Related Skills

# Check each required section
for section in "## When to Use" "## Inputs" "## Procedure" "## Common Pitfalls" "## Related Skills"; do
  grep -q "$section" skills/<skill-name>/SKILL.md && echo "$section: OK" || echo "$section: MISSING"
done

# Validation section may use either heading
grep -qE "## Validation( Checklist)?" skills/<skill-name>/SKILL.md && echo "Validation: OK" || echo "Validation: MISSING"

Expected: All six sections present. Procedure section contains at least one ### Step sub-heading.

On failure: Report each missing section as BLOCKING. A skill without all six sections is non-compliant with the agentskills.io standard. Provide the section template from the create-skill meta-skill.

Step 4: Check Procedure Step Format

Verify each procedure step follows the required pattern: numbered step title, context, code block(s), and Expected:/On failure: blocks.

For each ### Step N: sub-section, check:

The step has a descriptive title (not just "Step N")
At least one code block or concrete instruction exists
An **Expected:** block is present
An **On failure:** block is present

Expected: Every procedure step has both Expected: and On failure: blocks. Steps contain concrete code or instructions, not vague descriptions.

On failure: Report each step missing Expected/On failure as BLOCKING. If steps contain only vague instructions ("configure the system appropriately"), report as SUGGEST with a note to add concrete commands.

Step 5: Verify Line Count

Check that the SKILL.md is within the 500-line limit.

lines=$(wc -l < skills/<skill-name>/SKILL.md)
[ "$lines" -le 500 ] && echo "OK ($lines lines)" || echo "OVER LIMIT ($lines lines > 500)"

Expected: Line count is 500 or fewer.

On failure: If over 500 lines, report as BLOCKING. Recommend using the refactor-skill-structure skill to extract code blocks >15 lines to references/EXAMPLES.md. Typical reduction: 20-40% by extracting extended examples.

Step 6: Check Registry Synchronization

Verify the skill is listed in skills/_registry.yml under the correct domain with matching metadata.

Check:

Skill id exists under the correct domain section
path matches <skill-name>/SKILL.md
complexity matches frontmatter
description is present (may be abbreviated)
total_skills count at the top of the registry matches actual skill count

# Check if skill is in registry
grep -q "id: <skill-name>" skills/_registry.yml && echo "Registry: FOUND" || echo "Registry: NOT FOUND"

# Check path
grep -A1 "id: <skill-name>" skills/_registry.yml | grep -q "path: <skill-name>/SKILL.md" && echo "Path: OK" || echo "Path: MISMATCH"

Expected: Skill is listed in the registry under the correct domain with matching path and metadata. Total count is accurate.

On failure: If not found in registry, report as BLOCKING. Provide the registry entry template:

- id: skill-name
  path: skill-name/SKILL.md
  complexity: intermediate
  language: multi
  description: One-line description

Validation

Common Pitfalls

Checking frontmatter with regex only: YAML parsing can be subtle. A description: > multiline block looks different from description: "inline". Check both patterns when searching for fields.
Missing the Validation section variant: Some skills use ## Validation Checklist instead of ## Validation. Both are acceptable; check for either heading.
Forgetting registry total count: After adding a skill to the registry, the total_skills number at the top must also be incremented. This is a common miss in PRs.
Name vs. title confusion: The name field must be kebab-case matching the directory name. The # Title heading is human-readable and can differ (e.g., name: review-skill-format, title: # Review Skill Format).
Lenient mode skipping blockers: Even in lenient mode, missing required sections and frontmatter fields should still be flagged. Lenient mode only relaxes style and metadata recommendations.

Related Skills

create-skill — The canonical format specification; use as the authoritative reference for what a valid SKILL.md looks like
update-skill-content — After format validation passes, use this to improve content quality
refactor-skill-structure — When a skill fails the line count check, use this to extract and reorganize
review-pull-request — When reviewing a PR that adds or modifies skills, combine PR review with format validation

review-skill-format