Validate Skill

A GitHub Action to validate SKILL.md files against the Agent Skills specification.

Why Use This Action?

• Cross-agent compatibility - Ensure your skill works across all coding agents that support the Agent Skills spec
• CLI compatibility - Valid skills install correctly with tools like the Vercel Skills CLI
• Catch errors early - Validate skills in CI before they reach production
• Spec compliance - Ensure your SKILL.md follows the official Agent Skills specification
• Configurable - Ignore specific rules, enforce directory structures, or run in strict mode
• Reference checking - Verify that file references in your skill actually exist
• CI-friendly outputs - JSON arrays for errors and warnings for programmatic use

Usage

Basic Usage

- name: Validate SKILL.md
  uses: Flash-Brew-Digital/validate-skill@v1
  with:
    path: ./my-skill

See the examples folder for basic GitHub workflow files you can copy and use:

• Simple example - Basic single-skill validation
• Advanced example - Detect and validate only changed skills

Inputs

Input	Description	Required	Default
path	Path to the skill directory containing SKILL.md	No	.
fail-on-warning	Treat warnings as errors	No	false
ignore-rules	Comma-separated list of rule IDs to ignore (e.g., name-match-directory)	No	""
enforce-directories	Comma-separated list of directories the skill must include (e.g., scripts)	No	""
validate-references	Check that file references in SKILL.md actually exist	No	false

Outputs

Output	Description
valid	Whether the SKILL.md is valid (true/false)
errors	JSON array of validation errors
warnings	JSON array of validation warnings

Example: Using Outputs

- name: Validate SKILL.md
  id: validate
  uses: Flash-Brew-Digital/validate-skill@v1
  with:
    path: ./my-skill

- name: Check results
  if: always()
  run: |
    echo "Valid: ${{ steps.validate.outputs.valid }}"
    echo "Errors: ${{ steps.validate.outputs.errors }}"
    echo "Warnings: ${{ steps.validate.outputs.warnings }}"

Example: Ignore Specific Rules

- name: Validate SKILL.md
  uses: Flash-Brew-Digital/validate-skill@v1
  with:
    path: ./my-skill
    ignore-rules: name-match-directory,description-quality

Example: Enforce Directory Structure

- name: Validate SKILL.md
  uses: Flash-Brew-Digital/validate-skill@v1
  with:
    path: ./my-skill
    enforce-directories: scripts,references

Example: Validate File References

- name: Validate SKILL.md
  uses: Flash-Brew-Digital/validate-skill@v1
  with:
    path: ./my-skill
    validate-references: "true"

Example: Strict Mode (Fail on Warnings)

- name: Validate SKILL.md (strict)
  uses: Flash-Brew-Digital/validate-skill@v1
  with:
    path: ./my-skill
    fail-on-warning: "true"

What Gets Validated

This action validates your SKILL.md against the Agent Skills specification:

Required Fields

• name: Must be 1-64 characters, lowercase alphanumeric with hyphens, no leading/trailing/consecutive hyphens, must match directory name
• description: Must be 1-1024 characters, non-empty

Optional Fields

• license: Must be a string if provided
• compatibility: Must be 1-500 characters if provided
• metadata: Must be a key-value mapping with string values
• allowed-tools: Must be a space-delimited string

Structure

• YAML frontmatter must be present (between --- markers)
• Frontmatter must be valid YAML

Warnings

The action also produces warnings for:

• Very short descriptions (< 50 characters)
• Empty body content
• Body exceeding 500 lines
• Unknown fields in frontmatter

Valid SKILL.md Example

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Designed for Claude Code
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing Skill

Instructions for agents on how to process PDFs...

The 'name' and 'description' fields are required. Other fields are optional.

Install Agent Skills

To install an Agent Skill from a GitHub repository, use the below command. See the Vercel Skills CLI documentation for more information.

npx skills add <owner/repo>

Resources

• Agent Skills specification
• Agent Skills directory

Contributing

Contributions are welcome! Please read our Contributing Guide for more information.

License

MIT License

Author

Ben Sabic at Flash Brew Digital