What Is the Purpose of the `validate_skill.py` Script? A Complete Guide

validate_skill.py is a linting and validation utility that checks a repository's SKILL.md file for compliance with the formal Agent Skills specification and host-specific rules for AI lenses including Claude, GitHub Copilot CLI, Sourcegraph Amp, and Hermes Agent.

The validate_skill.py script serves as the quality gate for the virgiliojr94/book-to-skill repository, ensuring that skill definitions remain portable, correctly structured, and compatible with multiple AI agent platforms. By validating YAML front-matter, enforcing field requirements, and checking tool declarations against known lens capabilities, it prevents malformed skills from entering the codebase.

How validate_skill.py Validates Skill Definitions

The script operates as a standalone Python utility located at tools/validate_skill.py. It requires no external dependencies, making it ideal for continuous integration environments.

Command-Line Interface and Basic Usage

The script accepts two primary arguments: the path to a skill file and the target lens for validation.

# Validate with default Claude lens

python3 tools/validate_skill.py

# Validate against GitHub Copilot CLI rules

python3 tools/validate_skill.py --lens copilot

# Validate a custom skill file with Amp lens

python3 tools/validate_skill.py path/to/CustomSkill.md --lens amp

The default lens is Claude, with --lens supporting: claude, copilot, amp, and hermes.

Core Validation Architecture

Understanding the internal structure of validate_skill.py helps explain its comprehensive checking capabilities.

Lens Definitions and Platform-Specific Rules

The script encodes platform requirements in the LENSES dictionary (lines 58-86). Each lens supplies:

• Recognized built-in tools
• Allowed front-matter keys
• Reserved words that cannot appear in skill names
• Severity levels for different violation types

This architecture enables multi-platform validation without maintaining separate scripts per target.

Front-Matter Parsing and Field Extraction

The script implements specialized utilities for processing Markdown with YAML front-matter:

• parse_frontmatter() (lines 9-15) — isolates the YAML block from the body content
• get_scalar() and get_list_items() (lines 18-35) — extract scalar values and list items respectively

These functions enable robust handling of the SKILL.md structure regardless of minor formatting variations.

The audit() Function: Core Validation Logic

The audit() function orchestrates all validation checks. Here are the specific validations performed:

Name Field Validation (lines 59-73)

• Presence check (name is required)
• Length limits enforcement
• Pattern matching against allowed characters
• Reserved word restrictions (lens-specific prohibited terms)

Description Validation (lines 74-85)

• Presence requirement
• Hard length limits
• Optional soft-limit warnings for readability

Allowed-Tools Analysis (lines 86-117) The most complex validation checks that declared tools match the lens's known capabilities:

• Validates each tool in allowed-tools against the lens's built-in set
• Detects Bash usage patterns when shell execution is declared
• Flags unknown or disallowed tool tokens
• Reports tools that may behave differently across lenses

Additional Quality Checks (lines 118-125)

• Unrecognized top-level front-matter keys
• Body line count warnings for oversized skills

UTF-8 Output Handling

The script forces UTF-8 encoding on stdout/stderr (lines 35-42) to ensure check-mark glyphs (✓) and cross marks (✗) render correctly across all terminal environments.

CI/CD Integration and Exit Behavior

validate_skill.py is designed as a continuous integration gate. It exits with non-zero status when ERROR conditions are detected, halting merges that would introduce incompatible skills.

GitHub Actions Example

- name: Validate skill across all lenses
  run: |
    python3 tools/validate_skill.py --lens ${{ matrix.lens }}
  env:
    matrix:
      lens: [claude, copilot, amp, hermes]

This matrix strategy ensures a single SKILL.md complies with all four supported platforms before approval.

Result Reporting Format

Validation results use consistent prefixes for machine parsing:

• ERROR: — blocking violations that cause non-zero exit
• WARN: — advisory issues that do not block
• Final status line with ✓ or ✗ emoji (lines 128-146)

Skill Validation in the Repository Workflow

The script sits at a critical point in the book-to-skill architecture. According to AGENTS.md and CONTRIBUTING.md, validation occurs after skill authoring and before any generation or extraction operations.

The validation step precedes:

• Content extraction from source books
• Skill generation for target platforms
• Repository contributions and pull requests

This ordering ensures that invalid skills never propagate to downstream processing stages.

Summary

• validate_skill.py is a self-contained, dependency-free validation utility for SKILL.md files
• Supports four AI lenses: Claude (default), GitHub Copilot CLI, Sourcegraph Amp, and Hermes Agent
• Validates required fields: name, description, and allowed-tools with lens-specific rules
• Enforces quality constraints: length limits, reserved words, unknown keys, and body size
• Designed for CI integration: non-zero exit on ERROR conditions enables automated blocking
• Located at tools/validate_skill.py with no external dependencies beyond Python 3

Frequently Asked Questions

What file does validate_skill.py check by default?

By default, validate_skill.py validates SKILL.md in the current working directory. You can specify an alternative path as the first positional argument, such as python3 tools/validate_skill.py path/to/AnotherSkill.md.

Why does the script exit with non-zero status?

The non-zero exit code occurs only when ERROR severity violations are found. This design enables the script to function as a CI gate—failing builds before malformed skills merge into the repository. Warnings alone do not trigger failure.

What happens if I declare a tool not supported by my target lens?

The audit() function's allowed-tools analysis (lines 86-117) flags unknown tool tokens as errors or warnings depending on lens configuration. For maximum portability, skills should restrict themselves to the intersection of tools supported across all target lenses.

Can I run validation without installing dependencies?

Yes. validate_skill.py uses only Python 3 standard library modules. It requires no pip install step, making it safe to run in minimal CI containers and fresh clones of the virgiliojr94/book-to-skill repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}