Skill Standardization

When to use this skill

• Creating a new SKILL.md file from scratch

• Auditing existing skills for Agent Skills specification compliance

• Converting legacy skill formats (non-standard headings, frontmatter) to standard

• Improving skill descriptions to trigger more reliably on relevant prompts

• Adding evaluation test cases (evals/evals.json ) to a skill

• Batch-validating all skills in a directory for consistency

Agent Skills Specification Reference

Frontmatter fields

Field Required Constraints

name

Yes 1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match parent directory name

description

Yes 1–1024 chars, must describe what skill does AND when to trigger

allowed-tools

No Space-delimited list of pre-approved tools

compatibility

No Max 500 chars, environment requirements

license

No License name or reference to bundled file

metadata

No Arbitrary key-value map for additional fields

Standard directory structure

skill-name/ ├── SKILL.md # Required ├── scripts/ # Optional: executable scripts ├── references/ # Optional: detailed documentation ├── assets/ # Optional: templates, images, data └── evals/ # Optional: evaluation test cases └── evals.json

Progressive disclosure tiers

Tier What's loaded When Token budget

1. Catalog name + description Session start ~100 tokens per skill

2. Instructions Full SKILL.md body On activation < 5000 tokens (500 lines max)

3. Resources scripts/, references/ When needed Varies

Instructions

Step 1: Validate an existing skill

Run the validation script on a skill directory:

bash scripts/validate_skill.sh path/to/skill-directory

Validate all skills in a directory:

bash scripts/validate_skill.sh --all .agent-skills/

The script checks:

• Required frontmatter fields (name , description )

• name format: lowercase, no consecutive hyphens, matches directory name

• description length: 1–1024 characters

• allowed-tools format: space-delimited (not YAML list)

• Recommended sections present

• File length: warns if over 500 lines

Step 2: Write an effective description

The description field determines when a skill triggers. A weak description means the skill never activates; an over-broad one triggers at wrong times.

Template:

description: > [What the skill does — list specific operations.] Use when [trigger conditions]. Even if the user doesn't explicitly mention [domain keyword] — also triggers on: [synonym list].

Principles (from agentskills.io):

• Imperative phrasing — "Use this skill when..." not "This skill does..."

• User intent, not implementation — describe what the user wants to achieve

• Be explicit about edge cases — "even if they don't say X"

• List trigger keywords — synonyms, related terms the user might type

• Stay under 1024 characters — descriptions grow during editing; watch the limit

Before / After:

Before (weak — never triggers)

description: Helps with PDFs.

After (optimized — reliable triggering)

description: > Extract text and tables from PDF files, fill forms, merge and split documents. Use when the user needs to work with PDF files, even if they don't explicitly say 'PDF' — triggers on: fill form, extract text from document, merge files, read scanned pages.

Step 3: Create a new SKILL.md

Use this template as the starting point:

name: skill-name description: > [What it does and specific operations it handles.] Use when [trigger conditions]. Triggers on: [keyword list]. allowed-tools: Bash Read Write Edit Glob Grep metadata: tags: tag1, tag2, tag3 version: "1.0"

Skill Title

When to use this skill

• Scenario 1
• Scenario 2

Instructions

Step 1: [Action]

Content...

Step 2: [Action]

Content...

Examples

Example 1: [Scenario]

Input: ... Output: ...

Best practices

1. Practice 1
2. Practice 2

References

• Link

Step 4: Convert legacy section headings

Legacy heading Standard heading

Purpose

When to use this skill

When to Use

When to use this skill

Procedure

Instructions

Best Practices

Best practices

Reference

References

Output Format

Output format

Step 5: Add evaluation test cases

Create evals/evals.json with 2–5 realistic test prompts:

{ "skill_name": "your-skill-name", "evals": [ { "id": 1, "prompt": "Realistic user message that should trigger this skill", "expected_output": "Description of what success looks like", "assertions": [ "Specific verifiable claim (file exists, count is correct, format is valid)", "Another specific claim" ] } ] }

Good assertions are verifiable: file exists, JSON is valid, chart has 3 bars. Avoid vague assertions like "output is good."

Available scripts

• scripts/validate_skill.sh — Validates a SKILL.md against the Agent Skills spec

Examples

Example 1: Validate a skill directory

bash scripts/validate_skill.sh .agent-skills/my-skill/

Output:

Validating: .agent-skills/my-skill/SKILL.md ✓ Required field: name = 'my-skill' ✓ Required field: description present ✗ Description length: 1087 chars (max 1024) ✓ Name format: valid lowercase ✗ Name/directory mismatch: name='myskill' vs dir='my-skill' ✓ Recommended section: When to use this skill ✓ Recommended section: Instructions ⚠ Missing recommended section: Examples ✓ File length: 234 lines (OK)

Issues: 2 errors, 1 warning

Example 2: Batch validate all skills

bash scripts/validate_skill.sh --all .agent-skills/

Example 3: Fix common frontmatter issues

WRONG — tags inside metadata is non-standard for some validators

metadata: tags: [tag1, tag2] # list syntax platforms: Claude # non-spec field

CORRECT — per Agent Skills spec

metadata: tags: tag1, tag2 # string value allowed-tools: Bash Read Write # space-delimited, not a YAML list

Best practices

• Description quality first — weak descriptions mean the skill never activates; improve it before anything else

• Keep SKILL.md under 500 lines — move detailed reference docs to references/

• Pin script versions — use uvx ruff@0.8.0 not just ruff to ensure reproducibility

• No interactive prompts in scripts — agents run in non-interactive shells; use --flag inputs, never TTY prompts

• Structured output from scripts — prefer JSON/CSV over free-form text; send data to stdout, diagnostics to stderr

• Add evals before publishing — at least 2–3 test cases covering core and edge cases

References

• Agent Skills Specification

• Optimizing Descriptions

• Evaluating Skills

• Using Scripts

• Adding Skills Support