Agent-almanac review-skill-format

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/caveman-ultra/skills/review-skill-format" ~/.claude/skills/pjt222-agent-almanac-review-skill-format-fa51f3 && rm -rf "$T"

manifest: i18n/caveman-ultra/skills/review-skill-format/SKILL.md

source content

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.

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
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.
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:

```
## 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 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:

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

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

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