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

> Easily validate a single skill's integrity with the Claude Skills validation script. Learn to use the scriptsvalidate skills.py --skill argument for quick error detection and ensure your AI skills are robust.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Use the `--skill` argument with [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py), the argument parser defines the `--skill` option:

```python
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:

```python
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:

```python
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:

```python
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:

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-markdown.py) | Contains additional markdown-specific validators that [`validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-skills.py) may invoke for deep content analysis. |

## Summary

- Use **`--skill <name>`** with [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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.