How to Validate a Single Skill's Integrity Using the Claude Skills Validation Script

Use the --skill argument with scripts/validate-skills.py to execute the complete validation suite against an individual skill directory, exiting with code 1 if any integrity errors are detected.

The Jeffallan/claude-skills repository provides a robust validation framework to ensure every Claude Skill meets structural and content standards. When you need to validate a single skill's integrity—rather than scanning the entire repository—the standalone validator offers a targeted mode that isolates one skill directory and runs the full suite of YAML front-matter, reference file, and formatting checks.

How the Single-Skill Validator Works

Argument Parsing for Targeted Validation

At lines 1852–1856 of scripts/validate-skills.py, the argument parser defines the --skill option:

parser.add_argument("--skill", help="Validate only the specified skill")

This flag accepts a string value representing the exact name of the skill directory you want to validate.

Skill Directory Filtering

The SkillValidator class implements the filtering logic at lines 1801–1805. When --skill is provided, the validator constructs a filtered list containing only the matching directory:

if self.skill_filter:
    skill_dirs = [d for d in skill_dirs if d.name == self.skill_filter]

If no match is found, the validator exits early with an appropriate message.

Check Execution and Issue Aggregation

For the selected directory, the validator iterates over all registered checkers—including YAML front-matter validation, required field checks, name format validation, description rules, and reference file verification—at lines 1807–1812:

for checker in self.checkers:
    issues = checker.check(skill_dir)
    result.issues.extend(issues)

Each checker returns a list of ValidationIssue objects that are aggregated into the final report.

Exit Code Behavior

At lines 1900–1904, the script sets the process exit code based on the presence of errors:

sys.exit(1 if report.has_errors else 0)

This makes the validator suitable for CI/CD pipelines that rely on non-zero exit codes to detect failures.

How to Validate a Single Skill's Integrity: Practical Examples

Basic Table Output

Run the validator against one skill to see a human-readable report:

python scripts/validate-skills.py --skill wordpress-pro

The output displays a colored table listing any warnings or errors detected in the wordpress-pro skill directory. The command returns exit code 1 if integrity errors exist.

JSON Output for Automation

For CI pipelines or programmatic consumption, use the JSON format:

python scripts/validate-skills.py --skill laravel-specialist --format json

This outputs a structured JSON document containing a results array with detailed ValidationIssue objects, including severity levels, line numbers, and remediation messages.

Filtering by Check Category

Combine --skill with the --check flag to run only specific validators:

# Validate only YAML front-matter for the specified skill

python scripts/validate-skills.py --skill legacy-modernizer --check yaml

Omitting --check runs the complete suite, including reference file validation and markdown structure checks.

Core Source Files and Implementation Details

File	Role in Single-Skill Validation
scripts/validate-skills.py	Main entry point. Parses --skill at lines 1852–1856, filters directories at lines 1801–1805, executes checkers at lines 1807–1812, and manages exit codes at lines 1900–1904.
skills/<skill-name>/SKILL.md	Target file inspected by YamlChecker and DescriptionFormatChecker for front-matter compliance and content structure.
skills/<skill-name>/references/	Directory validated by ReferencesDirectoryChecker and ReferenceFileCountChecker when reference checks are enabled.
scripts/validate-markdown.py	Contains additional markdown-specific validators that validate-skills.py may invoke for deep content analysis.

Summary

• Use --skill <name> with scripts/validate-skills.py to isolate validation to one directory.
• The validator executes the full suite of checks (YAML front-matter, references, formatting) against the single skill.
• Exit code 1 indicates integrity errors, making the script ideal for CI/CD integration.
• Filter specific check categories using --check (e.g., yaml, references) to narrow the scope further.
• All validation logic is centralized in scripts/validate-skills.py with clear line-number references for the argument parser, filtering logic, and exit handling.

Frequently Asked Questions

How do I validate a single skill's integrity without checking the entire repository?

Run python scripts/validate-skills.py --skill <skill-name>. This flag instructs the SkillValidator class to filter the skills/ directory tree to only the matching skill name before executing any checks, providing isolated feedback in seconds.

What exit code does the validation script return when a skill fails integrity checks?

The script returns exit code 1 when any error-level ValidationIssue is detected, and 0 when only warnings or no issues are present. This behavior, implemented at lines 1900–1904 of scripts/validate-skills.py, allows CI pipelines to halt builds automatically when skill integrity is compromised.

Can I combine the --skill flag with other filtering options?

Yes. You can pair --skill with --check to limit validation to specific categories (e.g., --check yaml for front-matter only) or with --format json for machine-readable output. The argument parser processes these flags independently, applying the skill filter first, then executing only the requested checkers against that single directory.

Which specific integrity checks run when I validate a single skill?

The validator runs the complete set of YAML front-matter checks (required fields, name format, description rules), reference file validation (directory structure, file counts), and markdown structure checks (section ordering, line counts). These are the same checks used during full-repository scans, ensuring consistent quality standards regardless of validation scope.

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