manifestspec

Zero-dependency Python validator for agent skill SKILL.md frontmatter, section structure, and skill.yaml capability manifests — fixes all known skill-lint.js bugs.

Parses and validates SKILL.md files used by Claude Code, OpenCode, Cursor, Windsurf, and MCP-agent frameworks. Fixes all four documented bugs in skill-lint.js.

Quick Start

# Install from source
cd /root/projects/manifestspec && pip install -e .

# Or install from PyPI (once published)
pip install manifestspec

from manifestspec import ManifestSpec, ValidationResult

result = ManifestSpec.from_skill_file("skills/code-review/SKILL.md")

if not result.is_valid:
    for error in result.errors:
        print(f"ERROR {error.code}: {error.message}")
    for warning in result.warnings:
        print(f"WARNING {warning.code}: {warning.message}")

print(result.is_valid)        # True / False
print(result.error_codes)     # ["MF_003", "MF_007", ...]
print(result.warning_codes)    # ["MF_W01", "MF_W02", ...]

# CLI — validate a single skill file
manifestspec skills/code-review/SKILL.md

# CLI — validate a directory of skills
manifestspec skills/

# CLI — fail on warnings (CI mode)
manifestspec --strict skills/

# CLI — JSON output for automation
manifestspec --json skills/

⚡ Performance & Benchmarks

manifestspec is the only Python-native, zero-dependency validator for agent skill manifests. It runs entirely in stdlib (re, yaml, pathlib) with no Node.js runtime dependency.

python3 benchmarks/run_benchmark.py

Why manifestspec?

The canonical skill validator, skill-lint.js, has four open bugs (issue #387):

manifestspec is the Python-native, zero-dependency reimplementation — no Node.js runtime required.

Key Features

• Frontmatter validation — YAML parsing, description length limits (≤1024 chars), kebab-case name enforcement
• Section structure checks — Required sections (Description, Triggers, Examples), fenced code blocks stripped before matching, ### sub-headings excluded
• Trigger phrase detection — Case-insensitive Use when, Use before, Use during; rejects negated forms (Do not use when)
• Cross-reference validation — [[skill-name]] and → skill-name syntax; excludes fenced blocks
• Capability manifests — Optional skill.yaml parsing for network/filesystem/secrets/tools declarations
• Library + CLI — Importable Python API and a manifestspec CLI for CI pipelines
• Corpus scanning — Validate entire skill directories with cross-ref resolution across files

API Reference

ManifestSpec

from manifestspec import ManifestSpec, Error, Warning

# Validate a single SKILL.md file
result: ValidationResult = ManifestSpec.from_skill_file("skills/code-review/SKILL.md")

# Validate an entire corpus
results: dict[Path, ValidationResult] = ManifestSpec.from_corpus("skills/")

ValidationResult

@dataclass
class ValidationResult:
    path: Path                    # Path to the validated file
    is_valid: bool                # True if no errors
    errors: list[Error]           # Hard validation failures
    warnings: list[Warning]        # Soft issues (name mismatch, unusual aliases)
    capabilities: CapabilitySpec | None  # skill.yaml data, if present

Error codes

CLI Reference

$ manifestspec --help
usage: manifestspec [-h] [--version] [--strict] [--json] [--no-color] [path]

Validate agent skill SKILL.md files.

positional arguments:
  path        SKILL.md file or directory of skills to validate (default: .)

options:
  -h, --help  show this help message and exit
  --version   Print version and exit.
  --strict    Exit non-zero if any warning is present.
  --json      Output results as JSON.
  --no-color  Disable color output.

Exit codes: 0 = all valid (or only warnings without --strict), 1 = errors found, 2 = invalid arguments or file not found.

Limitations

• PyYAML is stdlib-adjacent: Python's yaml module links against libyaml at the C level. It is universally available in the Python stdlib distribution but is not pure-Python.
• skill.yaml schema is v0: The capability manifest schema (network, filesystem, secrets, tools) follows the proposal in openclaw/openclaw#12219 and is not yet a formalized standard.
• Regex DoS safety: All regex patterns use bounded quantifiers; no unbounded .* that could cause pathological backtracking.
• Read-only: manifestspec validates but never writes or modifies SKILL.md files.
• No capability enforcement: skill.yaml is parsed but not enforced at runtime.

Non-goals

• Writing or modifying SKILL.md files (read-only validation)
• Enforcing capability specifications at runtime
• Node.js skill-lint.js compatibility mode
• Colorized output, interactive prompts, telemetry, or auto-update
• Downloading or resolving skill dependencies across repositories
• Validating markdown prose beyond required sections