Skip to content

Latest commit

 

History

History
265 lines (201 loc) · 7.35 KB

README.md

File metadata and controls

265 lines (201 loc) · 7.35 KB

Claude Code Plugin Template

🚀 Quick start template for creating high-quality Claude Code plugins with built-in validation, testing, and CI/CD.

Validate Plugin Security Scan

🎯 What You Get

This template provides:

  • ✅ Plugin Structure - Proper directory layout following Claude Code marketplace conventions
  • ✅ Validation Scripts - Automated naming, JSON schema, and frontmatter validation
  • ✅ GitHub Actions - CI/CD workflows for automatic validation on push/PR
  • ✅ ShellCheck Integration - Zero-warning shell script quality enforcement
  • ✅ Git Hooks - Pre-commit validation to catch issues before pushing
  • ✅ Testing Framework - Automated test suite for plugin functionality
  • ✅ Documentation Templates - Pre-filled docs with placeholders
  • ✅ Security Scanning - Automated secret detection and security checks
  • ✅ Compliance Framework - OWASP, CIS, NIST compliance documentation

🚀 Quick Start

1. Create Your Repository

Click "Use this template" button above, then:

# Clone your new repository
git clone https://github.com/YOUR_USERNAME/YOUR_PLUGIN.git
cd YOUR_PLUGIN

# Run setup script
./scripts/setup.sh

The setup script will:

  • Replace {{PLUGIN_NAME}} placeholders with your plugin name
  • Configure git hooks
  • Install validation dependencies
  • Create your first plugin structure

2. Customize Your Plugin

# Edit plugin metadata
nano .claude-plugin/plugin.json

# Create your first skill
mkdir -p skills/your-skill-name
nano skills/your-skill-name/skill.md

# Validate your changes
./scripts/validate-all.sh

3. Develop and Test

# Run validation
./scripts/validate-all.sh

# Run tests (if you have tests)
# ./tests/test-all.sh

# Install locally to test
/plugin marketplace add /path/to/your-plugin
/plugin install {{PLUGIN_NAME}}@{{PLUGIN_NAME}}-marketplace

4. Push and Deploy

git add .
git commit -m "feat: Initial plugin implementation"
git push

# GitHub Actions will automatically:
# - Validate your plugin
# - Run ShellCheck
# - Check security
# - Run tests

📁 Template Structure

your-plugin/
├── .github/workflows/        # CI/CD automation
│   ├── validate.yml         # Plugin validation
│   ├── security.yml         # Security scanning
│   └── test.yml             # Automated testing
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── skills/                  # Your plugin skills
│   └── example-skill/
│       └── skill.md         # Skill definition
├── agents/                  # Interactive tutors (optional)
│   └── example-tutor.md
├── hooks/                   # Git hooks (optional)
│   └── pre-commit.sh
├── scripts/                 # Validation and setup
│   ├── setup.sh            # First-time setup
│   ├── validate-all.sh     # Run all validations
│   ├── validate-naming.sh  # Naming conventions
│   ├── validate-json.sh    # JSON schema
│   └── validate-frontmatter.sh  # YAML frontmatter
├── tests/                   # Test suite
│   ├── test-all.sh
│   └── integration/
├── docs/                    # Documentation
│   ├── INSTALLATION.md
│   ├── CONTRIBUTING.md
│   └── CHANGELOG.md
├── .gitignore
├── LICENSE
└── README.md               # This file (update it!)

🎨 Customization Checklist

After using this template, customize these files:

  • .claude-plugin/plugin.json - Update name, description, author, keywords
  • README.md - Replace this content with your plugin description
  • skills/example-skill/skill.md - Create your actual skills
  • LICENSE - Update copyright year and name
  • docs/CHANGELOG.md - Start your version history
  • .github/workflows/*.yml - Update repository URLs in badges
  • Delete skills/example-skill/ after creating real skills

🔧 Development Workflow

Daily Development

# 1. Make changes
nano skills/my-skill/skill.md

# 2. Validate locally (pre-commit hook does this automatically)
./scripts/validate-all.sh

# 3. Test
./tests/test-all.sh

# 4. Commit (hook validates automatically)
git add .
git commit -m "feat: Add new skill"

# 5. Push (GitHub Actions validates automatically)
git push

Creating a New Skill

# Use the provided script
./scripts/create-skill.sh my-new-skill

# Or manually:
mkdir -p skills/my-new-skill
cat > skills/my-new-skill/skill.md << 'EOF'
---
name: my-new-skill
description: What this skill does
license: MIT
---

# My New Skill

## Activation Triggers
- "do something"
- "perform task"

## Behaviour
1. Step one
2. Step two
3. Step three
EOF

# Validate
./scripts/validate-all.sh

Version Management

# Update version in plugin.json
jq '.version = "1.1.0"' .claude-plugin/plugin.json > tmp.$$.json && mv tmp.$$.json .claude-plugin/plugin.json

# Update CHANGELOG.md
# Commit and tag
git add .
git commit -m "chore: Bump version to 1.1.0"
git tag -a v1.1.0 -m "Release v1.1.0"
git push && git push --tags

🛡️ Quality Standards

This template enforces:

ShellCheck (Zero Warnings)

All shell scripts must pass ShellCheck with no warnings:

find . -name "*.sh" -exec shellcheck {} \;

Naming Conventions

  • Directories: lowercase-with-hyphens (e.g., my-skill)
  • Pattern: ^[a-z0-9-]+$

JSON Schema

  • Author/Owner must be objects: {"name": "..."}
  • Semantic versioning: x.y.z
  • Required fields: name, version, description

Frontmatter

  • All skills must have valid YAML frontmatter
  • Required fields: name, description, license

Security

  • No hardcoded secrets
  • No CRLF line endings (LF only)
  • Proper file permissions

📚 Documentation

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

📄 License

MIT - See LICENSE for details

🌟 Powered By

This template is maintained by ZenterFlow and achieves:

  • 100% GitHub Actions pass rate
  • Zero ShellCheck warnings
  • 10/10 quality score
  • 100% compliance (OWASP, CIS, NIST, ISO 27001)

📖 Next Steps

  1. Customize - Replace placeholders with your plugin details
  2. Develop - Create your skills and agents
  3. Test - Use the validation and test scripts
  4. Deploy - Push to GitHub and let CI/CD validate
  5. Publish - Submit to Claude Code marketplace

Need help? Check out:

Happy coding! 🚀