---

name: review-skill-format locale: caveman source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-26" description: > Review SKILL.md file for compliance with agentskills.io standard. Checks YAML frontmatter fields, required sections, line count limits, procedure step format, registry synchronization. Use when new skill needs format validation before merge, existing skill modified and requires re-validation, performing batch audit of all skills in a domain, or reviewing contributor skill submission in pull request. license: MIT allowed-tools: Read Grep Glob metadata: author: Philipp Thoss version: "1.2" domain: review complexity: intermediate language: multi tags: review, skills, format, validation, agentskills, quality

Review Skill Format

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

When Use

• New skill authored and needs format validation before merge
• Existing skill modified and needs re-validation
• Performing batch audit of all skills in a domain
• Verifying skill created by create-skill meta-skill
• Reviewing contributor skill submission in a pull request

Inputs

• Required: Path to 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)

Steps

Step 1: Verify File Exists and Read Content

Confirm SKILL.md file exists at expected path. 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

Got: File exists and content readable. Line count displayed.

If fail: File does not exist? Check path for typos. Verify skill directory exists with ls skills/<skill-name>/. Directory missing? Skill not created yet — use create-skill first.

Step 2: Check YAML Frontmatter Fields

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

Required fields:

• name — matches directory name (kebab-case)
• description — under 1024 characters, starts with 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 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"

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

If fail: Report each missing field as BLOCKING. name does not match directory name? Report as BLOCKING with expected value. description exceeds 1024 characters? Report as SUGGEST with current length.

Step 3: Locale-Specific Validation (Translations Only)

Frontmatter contains locale field? File is translated SKILL.md. Perform these additional checks. No locale field? Skip this step.

1. Translation frontmatter fields — Verify these five fields present:

   • locale — target locale code (e.g., de, ja, zh-CN, es)
   • source_locale — origin locale (typically en)
   • source_commit — commit hash of English source used for translation
   • translator — who or what produced translation
   • translation_date — ISO 8601 date of translation

2. Prose language scan — Sample 3-5 body paragraphs (outside code blocks, frontmatter, headings). Verify prose written in target locale, not English. Ignore: code blocks, inline code, tool names, field names, file paths, English terms that have no standard translation in target language.

3. Code block identity check — Compare code blocks in translated file against English source at skills/<skill-name>/SKILL.md. Code blocks must be identical (code is never translated). Flag any code block whose content differs from English source.

# Check translation frontmatter fields
for field in "locale:" "source_locale:" "source_commit:" "translator:" "translation_date:"; do
  grep -q "^${field}\|^  ${field}" i18n/<locale>/skills/<skill-name>/SKILL.md \
    && echo "$field OK" || echo "$field MISSING"
done

Got: All five translation fields present. Body paragraphs in target locale. Code blocks match English source exactly.

If fail: Report missing translation fields as BLOCKING. Body paragraphs in English despite non-English locale? Report as BLOCKING — file has untranslated prose. Code blocks differ from English source? Report as BLOCKING — code must not be translated or modified.

Step 4: Check Required Sections

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

Required sections:

1. ## When to Use
2. ## Inputs
3. ## Procedure (with ### Step N: sub-sections)
4. ## Validation (may also appear as ## Validation Checklist)
5. ## Common Pitfalls
6. ## 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"

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

If fail: Report each missing section as BLOCKING. Skill without all six sections is non-compliant with agentskills.io standard. Provide section template from create-skill meta-skill.

Step 5: Check Procedure Step Format

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

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

1. Step has descriptive title (not just "Step N")
2. At least one code block or concrete instruction exists
3. **Expected:** block present
4. **On failure:** block present

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

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

Step 6: Verify Line Count

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

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

Got: Line count is 500 or fewer.

If fail: Over 500 lines? Report as BLOCKING. Recommend using refactor-skill-structure skill to extract code blocks >15 lines to references/EXAMPLES.md. Typical reduction: 20-40% by extracting extended examples.

Step 7: Check Registry Synchronization

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

Check:

1. Skill id exists under correct domain section
2. path matches <skill-name>/SKILL.md
3. complexity matches frontmatter
4. description present (may be abbreviated)
5. total_skills count at top of 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"

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

If fail: Not found in registry? Report as BLOCKING. Provide registry entry template:

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

Checks

• SKILL.md file exists at expected path
• YAML frontmatter parses without errors
• All four required frontmatter fields present (name, description, license, allowed-tools)
• All six metadata fields present (author, version, domain, complexity, language, tags)
• name field matches directory name
• description is under 1024 characters
• All six required sections present (When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills)
• Every procedure step has Expected: and On failure: blocks
• Line count is 500 or fewer
• Skill listed in _registry.yml with correct domain, path, metadata
• total_skills count in registry is accurate
• (Translations only) All five translation frontmatter fields present (locale, source_locale, source_commit, translator, translation_date)
• (Translations only) Body paragraphs in target locale, not English
• (Translations only) Code blocks identical to English source

Pitfalls

• Check frontmatter with regex only: YAML parsing can be subtle. description: > multiline block looks different from description: "inline". Check both patterns when searching for fields.
• Miss the Validation section variant: Some skills use ## Validation Checklist instead of ## Validation. Both acceptable; check for either heading.
• Forget registry total count: After add a skill to registry, total_skills number at top must also be incremented. Common miss in PRs.
• Name vs title confusion: name field must be kebab-case matching directory name. # Title heading is human-readable and can differ (e.g., name: review-skill-format, title: # Review Skill Format).
• Lenient mode skip blockers: Even in lenient mode, missing required sections and frontmatter fields should still be flagged. Lenient mode only relaxes style and metadata recommendations.
• Translated skills with English prose: File with non-English frontmatter, non-English headings, English body paragraphs passes all structural checks. Always verify body text language for translated skills — locale field in frontmatter signals that prose must be in target language, not English.

See Also

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