Skill Validation Script

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/validate-skills.sh
• skills/README.md
• skills/spec-driven-development/SKILL.md
• skills/ai-prompting/SKILL.md
• skills/quality-assurance/SKILL.md

The validate-skills.sh script is a quality assurance tool designed to enforce structural and content standards for all SKILL.md files within the skills/ directory. Its primary purpose is to ensure that each skill definition adheres to the project's conventions, which are based on the agentskills.io specification. By automating these checks, the script maintains consistency and quality across all defined skills, which is crucial for their integration and use by AI agents.

The script can be executed directly from the command line to validate all skills.

./scripts/validate-skills.sh

Sources: scripts/validate-skills.sh:61, skills/README.md:40-43

Validation Process

The script iterates through each subdirectory within the skills/ directory, looking for a SKILL.md file. For each file found, it performs a series of validation checks. If any check fails, it logs an error and increments an error counter. The script concludes by summarizing the number of skills found and the total number of errors, exiting with a non-zero status code if any errors were detected.

Sources: scripts/validate-skills.sh:13-20, scripts/validate-skills.sh:70-77

The following diagram illustrates the validation flow for a single SKILL.md file.

Validation Checks

The script performs a series of checks on the structure and frontmatter of each SKILL.md file.

SKILL.md Structure

A valid SKILL.md file must contain YAML frontmatter followed by Markdown content, including a main H1 heading.

Sources: skills/README.md:23-33, scripts/validate-skills.sh:22-26, 52-55

Frontmatter Validation

The script validates several required fields within the YAML frontmatter. The frontmatter is a set of key-value pairs that define the skill's metadata.

Sources: skills/spec-driven-development/SKILL.md:2-11, skills/ai-prompting/SKILL.md:2-11

Field	Validation Rule	Error/Warning Message
Frontmatter Start	The file must start with ---.	✗ Missing YAML frontmatter start (---)
name	The name field must be present.	✗ Missing required field: name
	The name must be 1-64 characters long.	✗ Name too long: X chars (max 64)
	The name must be lowercase alphanumeric with hyphens.	✗ Invalid name format: 'name'
description	The description field must be present.	✗ Missing required field: description

Sources: scripts/validate-skills.sh:22-50

The name format is validated using a regular expression.

if ! echo "$name" | grep -qE "^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$"; then
    echo "  ✗ Invalid name format: '$name'"
    ERRORS=$((ERRORS + 1))
fi

Sources: scripts/validate-skills.sh:36-39

Content Validation

After the frontmatter, the script checks for basic Markdown content structure.

Element	Validation Rule	Error/Warning Message
Main Heading	The file must contain a level 1 Markdown heading (e.g., # Skill Name).	✗ Missing main heading (# Title)
Content Length	A warning is issued if the file has fewer than 20 lines.	⚠ Warning: Very little content (X lines)

Sources: scripts/validate-skills.sh:52-60

Summary

The validate-skills.sh script acts as an essential CI/CD quality gate for the project. By enforcing a consistent structure for all SKILL.md files, it ensures that skills are well-defined, discoverable, and compatible with the systems that consume them. This automated validation is a key part of maintaining the integrity of the skill library as it grows.

Sources: scripts/validate-skills.sh