Implements the public Agent Skills specification

Validate your SKILL.md before an agent does

An independent Go CLI and GitHub Action that check skill directories against the Agent Skills specification. Stable rule IDs, line-accurate diagnostics, JSON for CI, and no network access.

curl -fsSL https://agent-skills-validator.coolapso.sh/install.sh | bash

View on GitHub Use the Action

Why use agent-skills-validator?

📐

Specification only

Every rule maps 1:1 to the public specification. No Markdown opinions, no host-specific fields, no repository conventions. Unknown keys and extra files are allowed, exactly as the spec says.

🎯

Actionable diagnostics

Each finding has a stable rule ID (AS001–AS010), a severity, the file, the line, and a message that tells you what to change.

🧾

Types preserved

Frontmatter is decoded with a real YAML parser, so version: 1.0 is caught as a float while "1.0" passes. Lengths count Unicode code points, not bytes.

🤖

Built for CI

Stable JSON output, documented exit codes, --strict and --fail-on-warnings flags, and a composite GitHub Action that needs no Go, Python or Node on the runner.

🔒

Offline and verified

Validation never touches the network. Release binaries ship with SHA-256 checksums that the install script and the Action verify before running anything.

💻

Cross-platform

Single static binary for Linux, macOS and Windows on amd64 and arm64, plus a multi-arch container image. LF and CRLF files, UTF-8 BOMs and malformed UTF-8 are all handled and reported clearly.

Installation

Pick whichever fits your machine. All options install the same static binary.

Install script (Linux, macOS)

Downloads the latest release, verifies the checksum and installs to /usr/local/bin. Set VERSION or INSTALL_DIR to override.

curl -fsSL https://agent-skills-validator.coolapso.sh/install.sh | bash

# a specific version
curl -fsSL https://agent-skills-validator.coolapso.sh/install.sh | VERSION=v1.0.0 bash

Remove it later with uninstall.sh.

Docker

Multi-arch images for linux/amd64 and linux/arm64 on the GitHub Container Registry and Docker Hub, built from scratch and running as a non-root user. Mount your repository on /data and pass skill paths relative to it.

docker run --rm -v "$PWD:/data:ro" ghcr.io/coolapso/agent-skills-validator:latest validate skills/my-skill

# Docker Hub, pinned version, machine-readable output
docker run --rm -v "$PWD:/data:ro" coolapso/agent-skills-validator:1.0.0 validate --format json skills/*/

GHCR tags · Docker Hub.

Go

Build and install from source with the Go toolchain.

go install github.com/coolapso/agent-skills-validator@latest

Arch Linux (AUR)

Prebuilt binary package.

yay -S agent-skills-validator-bin

Packages and binaries

.deb, .rpm, and archives for every platform, each listed in checksums.txt.

Go to the releases page →

Usage

Validate one or many skills

# one skill
agent-skills-validator validate ./skills/pdf-processing

# every skill, machine readable
agent-skills-validator validate --format json skills/*/

# recommendations are errors, any warning fails
agent-skills-validator validate --strict --fail-on-warnings ./my-skill

Exit codes

0	No errors. Warnings may be present unless `--fail-on-warnings` is set.
1	Validation errors, or warnings promoted to failures.
2	CLI misuse or an input path that does not exist.

What you get back

skills/pdf-processing: valid
skills/data/SKILL.md:2: error AS004: name "data-analysis" must match the skill directory name "data"
skills/data/SKILL.md:7: error AS008: metadata value for "version" must be a string, got a float; quote it if it is a number or boolean
skills/data/SKILL.md:501: warning AS010: SKILL.md has 512 lines; the specification recommends keeping it under 500 lines and moving detail into referenced files

2 skills validated, 1 valid, 1 invalid (2 errors, 1 warning)

Or as JSON

{
  "version": 1,
  "skills": [
    {
      "path": "skills/data",
      "valid": false,
      "diagnostics": [
        {
          "rule": "AS004",
          "severity": "error",
          "path": "skills/data/SKILL.md",
          "line": 2,
          "message": "name \"data-analysis\" must match the skill directory name \"data\""
        }
      ]
    }
  ]
}

Validation rules

One rule per requirement in the specification. Run agent-skills-validator rules to print this table and the specification revision baked into your binary.

ID	Severity	Rule
AS001	error	Target is a directory containing `SKILL.md`.
AS002	error	`SKILL.md` is valid UTF-8, begins with YAML frontmatter and has a closing delimiter.
AS003	error	`name` is a string of 1-64 Unicode lowercase alphanumeric characters or single hyphens; it does not start or end with a hyphen.
AS004	error	`name` matches the parent directory name.
AS005	error	`description` is a non-empty string of at most 1024 characters.
AS006	error	When present, `license` is a string.
AS007	error	When present, `compatibility` is a 1-500 character string.
AS008	error	When present, `metadata` is a mapping of string keys to string values.
AS009	error	When present, `allowed-tools` is a string.
AS010	warning	`SKILL.md` exceeds the specification's 500-line recommendation. Becomes an error with `--strict`.

Unknown frontmatter keys and extra files or directories are permitted by the specification and never produce diagnostics.

GitHub Action

The action downloads the release binary for the runner, verifies its checksum and runs it. Linux, macOS and Windows runners are supported.

jobs:
  validate-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: coolapso/agent-skills-validator@v0
        with:
          path: skills/terraform-skill
          strict: true

Inputs

path: Skill directory to validate. Default .
version: CLI release to download. Pinned per action release; latest is accepted.
strict: Pass --strict. Default false
fail-on-warnings: Pass --fail-on-warnings. Default false
format: text or json. With json the report is exposed through the json and json-file outputs.