Review Skill Format

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: Locale-Specific Validation (Translations Only)

If the frontmatter contains a locale field, the file is a translated SKILL.md. Perform these additional checks. If no locale field is present, skip this step.

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

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

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

3. Code block identity check — Compare code blocks in the translated file against the 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 the 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

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

On failure: Report missing translation fields as BLOCKING. If body paragraphs are in English despite a non-English locale, report as BLOCKING — the file has untranslated prose. If code blocks differ from the English source, report as BLOCKING — code must not be translated or modified.

Step 4: Check Required Sections

Verify all six required sections are present in the 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"

# Report pitfall count (create-skill cap: 3-6; evolve-skill evicts instead of appending past 6).
# Counts dash and numbered items; `|| true` guards grep's exit-1-on-zero under `set -e`.
pitfall_count=$(sed -n '/^## Common Pitfalls/,/^## [^#]/p' skills/<skill-name>/SKILL.md | grep -cE '^(- |[0-9]+\. )' || true)
echo "Common Pitfalls: $pitfall_count items (cap 3-6)"

Expected: All six sections present. Procedure section contains at least one ### Step sub-heading. Pitfall count is reported; 3-6 is within cap.

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. A pitfall count above 6 is SUGGEST, not BLOCKING — the count check is advisory by design: it cannot distinguish a grandfathered over-cap skill from fresh over-cap authoring, so enforcement of the 3-6 cap for new skills lives in create-skill at authoring time; recommend evicting the lowest-rediscovery-cost pitfall per evolve-skill. A count of 0 with the section present means a non-list format (e.g. a table) — count manually.

Step 5: 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:

1. The step has a descriptive title (not just "Step N")
2. At least one code block or concrete instruction exists
3. An **Expected:** block is present
4. 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 6: 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 7: Check Registry Synchronization

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

Check:

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

• SKILL.md file exists at the 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)
• Pitfall count reported (3-6 within cap; above-cap or 0-with-section-present noted as SUGGEST)
• Every procedure step has Expected: and On failure: blocks
• Line count is 500 or fewer
• Skill is listed in _registry.yml with correct domain, path, and 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 are in the target locale, not English
• (Translations only) Code blocks are identical to the English source

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.
• Translated skills with English prose: A file with non-English frontmatter, non-English headings, and English body paragraphs passes all structural checks. Always verify body text language for translated skills — the locale field in frontmatter signals that prose must be in the target language, not English.

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