Meta Agent Tools
PT

Back to the catalog

skill-validator

Health checker for Claude Code skills and commands. Scans ~/.claude/skills/ and commands/ for broken file references, deprecated MCP tool us

Open source Open in the app JSON README (API)

About

Health checker for Claude Code skills and commands. Scans ~/.claude/skills/ and commands/ for broken file references, deprecated MCP tool usage, missing frontmatter, script syntax errors, and outdated versions. Supports auto-fix with backup and GitHub update checking.

Details

Kind
Plugins
Topic
Government & public data
Publisher
aliksir
Origin
marketplace
Category
ferramentas
Stars
1
Last push
2026-05-31T16:37:29Z
Repository state
ativo
Language
JavaScript
License
MIT
Added
2026-08-30 01:48:58
Updated
2026-08-30 01:48:58
Origin id
aliksir/skill-validator/skill-validator

README

# claude-skill-validator

Validate and repair [Claude Code](https://claude.ai/code) skills — detect broken references, deprecated tools, syntax errors, and auto-fix issues.

Scans `~/.claude/skills/` and `~/.claude/commands/` in bulk to catch skill corruption caused by CLI updates, tool deprecations, or path changes.

[日本語 README](README.ja.md)

## Install

```bash
npm install -g claude-skill-validator
```

Or run without installing:

```bash
npx claude-skill-validator
```

## Usage

```bash
# Basic scan (scans ~/.claude by default)
claude-skill-validator

# Verbose output
claude-skill-validator --verbose

# Check for updates from source repositories
claude-skill-validator --update-check

# JSON output
claude-skill-validator --json

# Scan skills/ only
claude-skill-validator --skills-only

# Scan commands/ only
claude-skill-validator --commands-only

# Specify a custom Claude config directory
claude-skill-validator --dir /path/to/.claude

# Auto-fix fixable issues (with backup)
claude-skill-validator --fix

# Preview fixes without applying
claude-skill-validator --dry-run
```

## Check Types

| Check | What it verifies | Severity |
|-------|-----------------|----------|
| `frontmatter` | `name` and `description` fields exist in `SKILL.md` | WARN |
| `file-ref` | Referenced files in `INSTRUCTIONS.md`, `scripts/`, `references/` exist | FAIL |
| `tool-ref` | Deprecated MCP tool references are detected | FAIL |
| `cmd-ref` | Bash commands referenced in skills exist in PATH | WARN |
| `path-ref` | Hardcoded absolute paths exist on disk | WARN |
| `syntax` | `.js`, `.py`, `.sh` files in `scripts/` have valid syntax | FAIL |
| `update` | Skill source repositories have newer versions available | WARN |

## Output Example

```
📦 nano-banana
  ❌ [tool-ref] Deprecated tool reference: tabs_context_mcp (deprecated — use browser-cli)
  ❌ [tool-ref] Deprecated tool reference: read_page (deprecated — use browser-cli snapshot)

📦 api-design-reviewer
  ❌ [syntax] api_linter.py syntax error: SyntaxError: invalid syntax

============================================================
📊 Scan Summary
  Target directory: /Users/you/.claude
  Total checks: 450
  ✅ PASS: 380  ⚠️ WARN: 60  ❌ FAIL: 10
```

## Options

| Option | Description |
|--------|-------------|
| `--dir <path>` | Claude config directory (default: `~/.claude`) |
| `--skills-only` | Scan `skills/` directory only |
| `--commands-only` | Scan `commands/` directory only |
| `--json` | Output results as JSON |
| `--verbose` | Show all checks including PASS |
| `--quiet` | Show FAIL only; WARN count appears in summary |
| `--strict` | Show frontmatter WARN entries (hidden by default) |
| `--update-check` | Check for updates from source repositories |
| `--update` | Apply available updates (implies `--update-check`) |
| `--fix` | Auto-fix fixable issues (creates backups) |
| `--dry-run` | Preview fixes without applying changes |
| `--self-update` | Update `claude-skill-validator` itself to the latest version |
| `--no-version-check` | Skip npm version check (useful in CI) |
| `--help`, `-h` | Show help message |

## Plugin Commands (`commands/`)

This package ships two Claude Code slash commands in `commands/`:

| Command | File | What it does |
|---------|------|-------------|
| `/skill-validate` | `commands/skill-validate.md` | Run a full scan (all options exposed) |
| `/skill-validate-fix` | `commands/skill-validate-fix.md` | Guided dry-run → fix → verify flow |

Install the package globally and the commands become available in Claude Code immediately:

```bash
npm install -g claude-skill-validator
```

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | No issues (no FAILs) |
| `1` | FAILs found (action required) |
| `2` | Tool error |

## Requirements

- Node.js 18+
- No external dependencies (uses `fs`, `path`, `child_process`, `os` only)
- Works on Windows, macOS, and Linux

## License

MIT

More