Review Skill Format

Review Skill Format

Validate SKILL.md vs agentskills.io open std. Checks YAML frontmatter completeness, required section presence, proc step format (Expected/On failure blocks), line count limits, registry sync. Use before merging any new or modified skill.

Use When

• New skill authored + needs format validation before merge
• Existing skill modified + needs re-validation
• Batch audit of all skills in domain
• Verify skill created by create-skill meta-skill
• Review contributor skill submission in PR

In

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

Do

Step 1: Verify File + Read

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

→ File exists + content readable. Line count displayed.

If err: file doesn't exist → check path typos. Verify dir exists ls skills/<skill-name>/. Dir missing → skill not created → use create-skill first.

Step 2: Check Frontmatter Fields

Parse YAML frontmatter (between --- delimiters) + verify all required + recommended fields present.

Required:

• name — matches dir name (kebab-case)
• description — < 1024 chars, starts w/ verb
• license — typically MIT
• allowed-tools — comma or space-separated tool list

Recommended metadata:

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

# 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"

→ All 4 required fields present. All 6 metadata present. name matches dir. description < 1024 chars.

If err: report each missing as BLOCKING. name doesn't match dir → BLOCKING w/ expected value. description > 1024 chars → SUGGEST w/ current length.

Step 3: Locale-Specific Validation (Translations Only)

Frontmatter has locale field → file is translated SKILL.md. Perform additional checks. No locale → skip.

1. Translation frontmatter fields — Verify these 5 present:

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

2. Prose lang 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 w/ no std translation.

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

# 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

→ All 5 translation fields present. Body paragraphs in target locale. Code blocks match English source exactly.

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

Step 4: Check Required Sections

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

Required:

1. ## When to Use
2. ## Inputs
3. ## Procedure (w/ ### Step N: sub-sections)
4. ## Validation (may also ## 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"

→ All 6 sections present. Procedure section has ≥1 ### Step sub-heading.

If err: report each missing as BLOCKING. Skill w/o all 6 = non-compliant w/ agentskills.io. Provide section template from create-skill.

Step 5: Check Procedure Step Format

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

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

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

→ Every proc step has both Expected + On failure. Steps have concrete code or instr, not vague descriptions.

If err: report each step missing Expected/On failure as BLOCKING. Steps w/ only vague instrs ("configure system appropriately") → SUGGEST w/ note to add concrete cmds.

Step 6: Verify Line Count

Check SKILL.md ≤ 500-line limit.

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

→ Line count ≤ 500.

If err: > 500 → BLOCKING. Recommend refactor-skill-structure to extract code blocks > 15 lines → references/EXAMPLES.md. Typical reduction: 20-40% by extracting extended examples.

Step 7: Check Registry Sync

Verify skill listed in skills/_registry.yml under correct domain w/ 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 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"

→ Skill listed under correct domain w/ matching path + metadata. Total count accurate.

If err: not found in registry → BLOCKING. Provide entry template:

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

Check

• SKILL.md file exists at expected path
• YAML frontmatter parses w/o errors
• All 4 required frontmatter present (name, description, license, allowed-tools)
• All 6 metadata present (author, version, domain, complexity, language, tags)
• name field matches dir name
• description < 1024 chars
• All 6 required sections (When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills)
• Every proc step has Expected: + On failure:
• Line count ≤ 500
• Skill listed in _registry.yml w/ correct domain, path, metadata
• total_skills count in registry accurate
• (Translations only) All 5 translation 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

Traps

• Check frontmatter w/ regex only: YAML parsing subtle. description: > multiline diff from description: "inline". Check both patterns when searching.
• Miss Validation section variant: Some skills use ## Validation Checklist not ## Validation. Both acceptable; check for either.
• Forget registry total count: After adding skill to registry, total_skills must increment. Common miss in PRs.
• Name vs title confusion: name field = kebab-case matching dir. # Title heading = human-readable + can differ (e.g. name: review-skill-format, title: # Review Skill Format).
• Lenient mode skip blockers: Even lenient, missing required sections + frontmatter still flagged. Lenient only relaxes style + metadata.
• Translated skills w/ English prose: File w/ non-English frontmatter, headings, English body passes all structural checks. Always verify body lang for translated — locale field signals prose must be in target lang not English.

→

• create-skill — canonical format spec; authoritative ref for valid SKILL.md
• update-skill-content — after format validation passes, improve content quality
• refactor-skill-structure — skill fails line count → extract + reorganize
• review-pull-request — reviewing PR adding/modifying skills → combine w/ format validation