Claude Priority Validator - GitHub Action

Automatically validate Claude Code plugins for marketplace compliance in your CI/CD pipeline.

---

🎯 What Does This Do?

This GitHub Action automatically validates your Claude Code plugins to ensure they meet marketplace standards:

• ✅ Naming Conventions: Lowercase-with-hyphens for all 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

---

🚀 Quick Start

Basic Usage

Add this to .github/workflows/validate.yml:

name: Validate Plugin

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

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

      - name: Validate plugin compliance
        uses: ZenterFlow/claude-priority-action@v1
        with:
          plugin-path: '.'

That's it! Now every push and PR will automatically validate your plugin.

---

📋 Inputs

Input	Description	Required	Default
plugin-path	Path to the plugin directory	No	. (root)
fail-on-error	Fail workflow if validation errors found	No	true
check-naming	Validate naming conventions	No	true
check-json	Validate JSON schema	No	true
check-frontmatter	Validate YAML frontmatter	No	true
strict-mode	Enable strict validation mode	No	true
output-format	Output format: github, json, or text	No	github

---

📤 Outputs

Output	Description
validation-status	Overall status: pass or fail
total-checks	Total number of checks performed
passed-checks	Number of checks that passed
failed-checks	Number of checks that failed
error-messages	Detailed error messages (if any)

---

📖 Usage Examples

Example 1: Basic Validation

- name: Validate plugin
  uses: ZenterFlow/claude-priority-action@v1

Example 2: Custom Plugin Path

- name: Validate plugin in subdirectory
  uses: ZenterFlow/claude-priority-action@v1
  with:
    plugin-path: './plugins/my-plugin'

Example 3: Warning Mode (Don't Fail Build)

- name: Validate plugin (warnings only)
  uses: ZenterFlow/claude-priority-action@v1
  with:
    fail-on-error: false

Example 4: Selective Validation

- name: Validate only JSON schema
  uses: ZenterFlow/claude-priority-action@v1
  with:
    check-naming: false
    check-frontmatter: false
    check-json: true

Example 5: Use Outputs

- name: Validate plugin
  id: validate
  uses: ZenterFlow/claude-priority-action@v1

- name: Comment on PR
  if: failure()
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '❌ Validation failed!\n\n${{ steps.validate.outputs.error-messages }}'
      })

Example 6: Multiple Plugins

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        plugin: ['plugin-a', 'plugin-b', 'plugin-c']
    steps:
      - uses: actions/checkout@v4

      - name: Validate ${{ matrix.plugin }}
        uses: ZenterFlow/claude-priority-action@v1
        with:
          plugin-path: './plugins/${{ matrix.plugin }}'

Example 7: Pre-Merge Requirement

Block PR merges until validation passes:

name: Required Checks

on:
  pull_request:
    branches: [ main ]

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

      - name: Validate plugin (required)
        uses: ZenterFlow/claude-priority-action@v1
        with:
          strict-mode: true
          fail-on-error: true

Then in your repository settings:

1. Go to Settings → Branches
2. Add branch protection rule for main
3. Enable Require status checks to pass
4. Select Validate plugin (required)

Now PRs cannot be merged until validation passes! ✅

---

🎨 What You'll See

✅ 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

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

ℹ️  Validating plugin at: ./my-plugin

ℹ️  Checking naming conventions...
❌ Skill directory must be lowercase-with-hyphens: MySkill
❌ Naming conventions: FAILED (1 errors)

ℹ️  Checking JSON schema compliance...
❌ marketplace.json missing required field: version
❌ JSON schema: FAILED (1 errors)

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

══════════════════════════════════════════════════
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...

---

🧪 Local Testing

Want to test locally before pushing? Run the validation script directly:

# Clone the action
git clone https://github.com/ZenterFlow/claude-priority-dev.git
cd claude-priority-dev/.distributions/3-github-action

# Run validation
./validate.sh /path/to/your/plugin true true true true true

Or use the test suite:

cd tests
./test-action.sh

---

🐛 Troubleshooting

Error: "Plugin path does not exist"

Make sure you're checking out the code first:

steps:
  - uses: actions/checkout@v4  # ← Add this!
  - uses: ZenterFlow/claude-priority-action@v1

Error: "jq: command not found"

The action requires jq for JSON parsing. It's pre-installed on GitHub-hosted runners (ubuntu-latest, macos-latest, windows-latest).

If using a custom runner:

- name: Install dependencies
  run: sudo apt-get install -y jq

- name: Validate plugin
  uses: ZenterFlow/claude-priority-action@v1

Validation passes locally but fails in CI

Check line endings! Windows uses CRLF (\r\n) while Linux uses LF (\n).

Add .gitattributes:

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

Action shows warnings instead of errors

Set strict-mode: true and fail-on-error: true:

- uses: ZenterFlow/claude-priority-action@v1
  with:
    strict-mode: true
    fail-on-error: true

---

📊 Why Use This Action?

Before (Manual)

# Developer forgets to run validation
git push

# Plugin breaks production
# Users complain
# Emergency hotfix required

After (Automated)

# Every push automatically validated
# Errors caught before merge
# Zero defects in production
# Happy users! 🎉

Benefits

1. Catch Errors Early: Find issues before they reach production
2. Enforce Standards: Consistent quality across all plugins
3. Save Time: No manual validation required
4. Team Friendly: Everyone follows the same rules
5. PR Protection: Block merges until validation passes
6. Clear Feedback: Detailed error messages with line numbers

---

🤝 Integration Examples

With Code Review

name: PR Validation

on: pull_request

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

      - name: Validate plugin
        uses: ZenterFlow/claude-priority-action@v1

      - name: Request review if passed
        if: success()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.pulls.requestReviewers({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number,
              reviewers: ['tech-lead']
            })

With Notifications

- name: Validate plugin
  id: validate
  uses: ZenterFlow/claude-priority-action@v1

- name: Notify Slack
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "❌ Plugin validation failed: ${{ steps.validate.outputs.error-messages }}"
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

With Artifact Upload

- name: Validate plugin
  uses: ZenterFlow/claude-priority-action@v1

- name: Upload validation report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: validation-report
    path: validation-report.txt

---

📚 More Resources

• Documentation: Full validation guide
• Examples: Example plugins
• Issue Tracker: Report bugs
• Discussions: Ask questions

---

🎓 Learn More About GitHub Actions

New to GitHub Actions? Check out:

• GitHub Actions Documentation
• Workflow Syntax
• Marketplace

---

📄 License

MIT - See LICENSE for details

---

🙏 Contributing

Contributions welcome! See CONTRIBUTING.md

---

Built with ❤️ by ZenterFlow

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