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](url)

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

skill-standardization