Claude Plugin Validator

Validate Claude Code plugins for completeness and best practices before publishing.

Ensure your plugin meets quality standards with automated checks for required files, JSON validity, 2025 schema compliance, security vulnerabilities, and more.

Quick Start

# Run without installing (recommended)
npx claude-plugin-validator ./my-plugin

# Or install globally
npm install -g claude-plugin-validator
claude-plugin-validator ./my-plugin

What It Checks

✅ Required Files

• README.md - Plugin documentation
• LICENSE - Open source license (MIT recommended)
• .claude-plugin/plugin.json - Plugin manifest

📋 Configuration Validation

• Valid JSON syntax in all config files
• Required manifest fields (name, version, description, author)
• Semantic versioning format (x.y.z)
• Deprecated model identifiers (opus → sonnet/haiku)

🧩 Plugin Components

• At least one component directory (commands, agents, hooks, skills, scripts, mcp)
• Agent Skills frontmatter validation
• 2025 schema compliance (allowed-tools, version fields)
• Trigger phrase presence in skill descriptions

🔒 Security Checks

• No hardcoded passwords
• No hardcoded API keys
• No AWS credentials
• No private keys
• No dangerous commands (rm -rf /, eval())

🛠️ Script Quality

• Shell scripts are executable (chmod +x)
• No dangerous patterns in scripts

Output Example

============================================================
🔍 Validating Plugin: my-awesome-plugin
============================================================

📄 Checking Required Files...

📋 Validating Configuration Files...

🧩 Checking Plugin Components...

🔒 Security Checks...

============================================================
📊 VALIDATION REPORT
============================================================

✅ PASSED (15)
  ✓ README.md exists
  ✓ LICENSE exists
  ✓ .claude-plugin/plugin.json exists
  ✓ plugin.json has name
  ✓ plugin.json has version
  ✓ plugin.json has description
  ✓ plugin.json has author
  ✓ .claude-plugin/plugin.json is valid JSON
  ✓ Has 2 component(s): commands, skills
  ✓ Found 1 skill(s)
  ✓ Skill "my-skill" complies with 2025 schema
  ✓ Skill "my-skill" has description
  ✓ Script deploy.sh is executable
  ✓ No hardcoded secrets detected

⚠️  WARNINGS (1)
  ⚠ Skill "my-skill" description could include clearer trigger phrases

============================================================
🎯 SCORE: 90/95 (95%) - Grade: A
============================================================

🎉 Perfect! Your plugin is ready for publication!

Grading System

| Grade | Score | Status | |-------|-------|--------| | A | 90-100% | ✅ Ready for publication | | B | 80-89% | 👍 Good, address warnings | | C | 70-79% | ⚠️ Needs improvement | | D | 60-69% | ⚠️ Fix errors before publishing | | F | <60% | ❌ Not ready, fix critical issues |

Usage in CI/CD

Add to your GitHub Actions workflow:

name: Validate Plugin

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Plugin
        run: npx claude-plugin-validator ./

Exit Codes

• 0 - Validation passed (warnings allowed)
• 1 - Validation failed (critical errors found)

Common Issues

Missing LICENSE

❌ ERRORS (1)
  ✗ LICENSE missing (REQUIRED)

Fix: Add a LICENSE file (MIT recommended):

# Use MIT License template
curl -o LICENSE https://raw.githubusercontent.com/licenses/license-templates/master/templates/mit.txt

Invalid plugin.json

❌ ERRORS (1)
  ✗ .claude-plugin/plugin.json is invalid JSON

Fix: Validate JSON syntax:

cat .claude-plugin/plugin.json | jq

Deprecated Model Identifier

❌ ERRORS (1)
  ✗ plugin.json contains deprecated "opus" model identifier

Fix: Replace opus with sonnet or haiku:

{
  "model": "sonnet"  // for advanced reasoning
}

Script Not Executable

❌ ERRORS (1)
  ✗ Script deploy.sh is not executable (chmod +x)

Fix: Make scripts executable:

chmod +x scripts/*.sh

Missing 2025 Schema Fields

⚠️  WARNINGS (1)
  ⚠ Skill "my-skill" missing 2025 schema fields (allowed-tools, version)

Fix: Add frontmatter to SKILL.md:

---
name: my-skill
description: |
  What this skill does. Trigger phrases: "run analysis", "check performance"
allowed-tools: Read, Grep, Bash
version: 1.0.0
---

Programmatic Usage

const PluginValidator = require('claude-plugin-validator');

const validator = new PluginValidator('./my-plugin');
validator.validate();

// Access results
console.log(`Score: ${validator.score}/${validator.maxScore}`);
console.log(`Errors: ${validator.errors.length}`);
console.log(`Warnings: ${validator.warnings.length}`);

2025 Schema Compliance

The validator checks for Anthropic's 2025 Skills Schema compliance:

Required Fields

---
name: skill-name          # lowercase, hyphens, max 64 chars
description: |            # Clear "what" and "when" with trigger phrases
  What the skill does...
allowed-tools: Read, Write, Edit, Grep  # Tool permissions
version: 1.0.0           # Semantic versioning
---

Tool Categories

• Read-only: Read, Grep, Glob, Bash
• Code editing: Read, Write, Edit, Grep, Glob, Bash
• Web research: Read, WebFetch, WebSearch, Grep
• Database ops: Read, Write, Bash, Grep

Best Practices

1. README.md should include:

   • Clear description of what the plugin does
   • Installation instructions
   • Usage examples
   • Screenshots/demos (if applicable)

2. Skills should have:

   • Clear trigger phrases in description
   • Minimal allowed-tools for security
   • Version number for tracking updates

3. Security:

   • Never hardcode secrets
   • Use environment variables
   • Request minimal permissions
   • Validate all inputs in scripts

4. Scripts:

   • Make executable (chmod +x)
   • Add shebangs (#!/bin/bash)
   • Use ${CLAUDE_PLUGIN_ROOT} for paths

Contributing

Found a bug or want to add checks? Contribute at: github.com/jeremylongshore/claude-code-plugins

Resources

• Claude Code Docs: https://docs.claude.com/en/docs/claude-code/
• Plugin Marketplace: https://claudecodeplugins.io/
• Discord Community: https://discord.com/invite/6PPFFzqPDZ (#claude-code)

License

MIT © 2024-2025 Jeremy Longshore & Contributors

Made with ❤️ by the Claude Code Plugins community Visit claudecodeplugins.io for 253 production-ready plugins