stolt/skill-validator

A library for parsing and validating a SKILL.md file or raw SKILL.md content.

v0.0.3 2026-05-04 09:46 UTC

Requires

• php: >=8.2

Requires (Dev)

• dg/bypass-finals: ^1.9
• friendsofphp/php-cs-fixer: ^3.70.1
• peckphp/peck: ^0.1.2
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.4.4
• stolt/lean-package-validator: ^4.4

Suggests

• stolt/list-skills-command: Allows introspection of SKILL.md files from the console.

MIT

• Raphael Stolt

• php
• file
• parse
• parsing
• content
• validate
• validating
• ai
• skills
• agent-skills
• SKILL.md

README

A PHP library to parse and validate a SKILL.md file or raw SKILL.md content against the SKILL.md format specification.

Installation and usage

composer require stolt/skill-validator

Usage

The validator can validate either an existing SKILL.md file or raw SKILL.md content.

Validating a SKILL.md file

use Stolt\Ai\Skill\Validator;

$validator = new Validator();
$result = $validator->validateFile('/path/to/an-ai-skill/SKILL.md');

Validating raw SKILL.md content

use Stolt\Ai\Skill\Validator;

$validator = new Validator();
$result = $validator->validateContent('raw-skill-content');

Tip

The validate alias method accepts either a file path or raw content and delegates to the appropriate method automatically.

Accessing validation results and metadata

Validation returns a Stolt\Ai\Skill\ValidationResult object. When the SKILL.md content contains the required name and description fields, the parsed metadata is exposed as a Stolt\Ai\Skill\Metadata object.

use Stolt\Ai\Skill\Validator;

$validator = new Validator();
$result = $validator->validateContent('raw-skill-content');

if ($result->isInvalid()) {
    foreach ($result->errors() as $error) {
        echo $error . PHP_EOL;
    } 
    // Raw metadata can still be inspected when parsing succeeded but validation failed.
    $rawMetadata = $result->rawMetadata();
    exit(1);
} 

$metadata = $result->metadata();

if ($metadata === null) {
    throw new RuntimeException('Expected validated SKILL.md metadata.');
}

// Required SKILL.md metadata fields.
$name = $metadata->name();
$description = $metadata->description();

// Optional SKILL.md metadata fields.
$version = $metadata->version();
$tags = $metadata->tags();
$allowedTools = $metadata->get('allowed-tools', []);
$model = $metadata->get('model');
$effort = $metadata->get('effort');

// Markdown instructions after the YAML frontmatter.
$instructions = $result->body();

// Array representation for logging, JSON APIs, or integrations.
$arrayResult = $result->toArray();

echo sprintf('Skill "%s" is valid: %s', $name, $description) . PHP_EOL;

For an actual integration, the project list-skills-command can also be consolidated.

Validation rules

The validator checks that a SKILL.md document:

• starts with YAML frontmatter delimited by --- lines,
• contains the required name field,
• contains the required description field,
• uses a non-empty, lowercase, hyphenated skill name,
• contains Markdown instructions after the frontmatter,
• only uses supported frontmatter fields,
• uses lists for list-like fields such as tags, paths, and allowed-tools,
• uses a boolean value for disable-model-invocation.

Supported frontmatter fields include:

• name
• description
• when_to_use
• allowed-tools
• disable-model-invocation
• argument-hint
• arguments
• paths
• model
• effort
• metadata
• compatibility
• license
• author
• version
• tags

Running tests

composer test

License

This library is licensed under the MIT license. Please see LICENSE.md for more details.

Changelog

Please see CHANGELOG.md for more details.

Inspiration

This library idea is inspired by the work on agent-skills-validator by ronaldtebrake.

Contributing

Please see CONTRIBUTING.md for more details.