Claude Priority - npm Package

Validate Claude Code plugins for marketplace compliance from the command line.

🚀 Quick Start

Use with npx (No Installation Required)

npx claude-priority validate

Or Install Globally

npm install -g claude-priority
claude-priority validate

Or Install as Dev Dependency

npm install --save-dev claude-priority
npx claude-priority validate

🎯 What Does This Do?

Validates your Claude Code plugins to ensure they meet marketplace standards:

• ✅ Naming Conventions: Lowercase-with-hyphens for directories and files
• ✅ JSON Schema: Valid marketplace.json with required fields
• ✅ Frontmatter Format: Proper YAML frontmatter in skill files
• ✅ Semantic Versioning: Correct version format (x.y.z)
• ✅ File Structure: Required files and directories exist

📖 Usage

Basic Commands

# Validate current directory
claude-priority validate

# Validate specific plugin
claude-priority validate ./my-plugin

# Check command (alias for validate)
claude-priority check ./my-plugin

# Show help
claude-priority help

# Show version
claude-priority version

Options

# Validate with options
claude-priority validate --plugin-path ./my-plugin

# Skip specific checks
claude-priority validate --no-naming
claude-priority validate --no-json
claude-priority validate --no-frontmatter

# Disable strict mode
claude-priority validate --no-strict

# Don't fail on errors (warnings only)
claude-priority validate --no-fail

💡 Use Cases

1. Local Development

# Quick check before commit
claude-priority validate

2. npm Scripts

Add to your package.json:

{
  "scripts": {
    "validate": "claude-priority validate",
    "precommit": "claude-priority validate",
    "test": "claude-priority validate && npm run test:unit"
  }
}

Then run:

npm run validate

3. CI/CD Integration

.github/workflows/validate.yml:

- name: Install dependencies
  run: npm install

- name: Validate plugin
  run: npx claude-priority validate

Or use the GitHub Action for better integration:

- uses: ZenterFlow/claude-priority-action@v1

📊 Output Examples

✅ Successful Validation

╔══════════════════════════════════════════════════╗
║   Claude Priority Validator                      ║
║   Ensuring marketplace compliance                ║
╚══════════════════════════════════════════════════╝

ℹ️  Validating plugin at: ./my-plugin

ℹ️  Checking naming conventions...
✅ Naming conventions: PASSED

ℹ️  Checking JSON schema compliance...
✅ JSON schema: PASSED

ℹ️  Checking YAML frontmatter format...
✅ Frontmatter format: PASSED

══════════════════════════════════════════════════
Validation Summary
══════════════════════════════════════════════════
Total checks:  3
Passed:        3
Failed:        0
══════════════════════════════════════════════════

✅ All validation checks passed! 🎉

❌ Failed Validation

❌ Skill directory must be lowercase-with-hyphens: MySkill
❌ marketplace.json missing required field: version

══════════════════════════════════════════════════
Validation Summary
══════════════════════════════════════════════════
Total checks:  3
Passed:        1
Failed:        2
══════════════════════════════════════════════════

❌ Validation failed with 2 failed checks

🔧 Validation Rules

Naming Conventions

• Plugin directory: my-plugin ✅, MyPlugin ❌
• Skill directories: format-code ✅, FormatCode ❌
• Files: skill.md ✅, Skill.md ❌

JSON Schema (marketplace.json)

Required fields:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": "Your Name"
}

Optional but recommended:

{
  "homepage": "https://github.com/user/plugin",
  "license": "MIT",
  "keywords": ["validation", "formatting"],
  "skills": ["skill-name"]
}

Frontmatter (skill.md)

Required format:

---
name: Skill Name
description: Brief description of the skill
---

# Skill content here...

🛠️ Requirements

• Node.js: >= 14.0.0
• bash: Required for validation script
• jq: Required for JSON parsing

Installing jq

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Fedora/RHEL
sudo dnf install jq

# Windows (with Chocolatey)
choco install jq

# NixOS
nix-env -i jq

🧪 Testing

Test the package locally before publishing:

# Link package locally
cd /path/to/claude-priority-npm
npm link

# Test in another directory
cd /path/to/your/plugin
claude-priority validate

# Unlink when done
npm unlink -g claude-priority

🐛 Troubleshooting

Error: "bash is not installed or not in PATH"

Windows users: Install Git Bash or WSL Mac/Linux: bash should be pre-installed

Error: "jq: command not found"

Install jq (see Requirements section above)

Error: "Plugin path does not exist"

Make sure you're in the correct directory or provide the full path:

claude-priority validate /full/path/to/plugin

Validation passes locally but fails in CI

Check line endings! Windows uses CRLF while Linux uses LF.

Add .gitattributes:

*.sh text eol=lf
*.md text eol=lf
*.json text eol=lf

🔗 Related Tools

• GitHub Action - Automate validation in CI/CD
• Development Repo - Full development environment
• Plugin Template - Template for new plugins

📄 License

MIT License - See LICENSE for details

🤝 Contributing

Contributions welcome!

• Report bugs: https://github.com/ZenterFlow/claude-priority-dev/issues
• Submit PRs: https://github.com/ZenterFlow/claude-priority-dev/pulls

📦 What's Next?

• 🐳 Docker Image - Run in containers
• 🦀 Rust Rewrite - 10x performance improvement
• 💻 VS Code Extension - Validate in your editor
• 🌐 Web Interface - Online validation tool

Built with ❤️ by ZenterFlow

Making Claude Code plugin development safer and easier, one validation at a time.