CONTRIBUTING.md

Contributing to Plugin Dev

Thank you for your interest in contributing to the Plugin Dev toolkit for Claude Code! This document provides guidelines and instructions for contributing.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• How to Contribute
• Development Guidelines
• Component-Specific Guidelines
• Testing
• Submitting Changes
• Style Guide
• Community

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to sjnims@gmail.com.

Getting Started

Prerequisites

Before contributing, ensure you have:

• Claude Code: Install from claude.ai/code
• GitHub CLI (gh): Installed and authenticated

  brew install gh  # macOS
  gh auth login

• Git: For version control
• markdownlint-cli2 and prettier: For linting (should be available globally)

  # Verify they're installed
  markdownlint-cli2 --version
  prettier --version

Understanding the Project

1. Read the documentation:

   • README.md - User-facing documentation
   • CLAUDE.md - Development documentation
   • SECURITY.md - Security policy

2. Explore the architecture:

   plugins/plugin-dev/
   ├── commands/      # 4 slash commands
   ├── skills/        # 10 skills
   └── agents/        # 3 specialized agents
   

3. Understand the plugin components:

   • 10 skills for different plugin development aspects
   • 3 agents for validation and generation
   • 4 slash commands: /plugin-dev:start, /plugin-dev:create-plugin, /plugin-dev:create-marketplace, /plugin-dev:plugin-dev-guide

Development Setup

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/plugin-dev.git
cd plugin-dev

2. Set Up Remote

git remote add upstream https://github.com/sjnims/plugin-dev.git

3. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

4. Test the Plugin

# From repository root
claude --plugin-dir plugins/plugin-dev

# Test command in Claude Code
/plugin-dev:create-plugin

5. Verify GitHub CLI Setup

gh auth status  # Should show logged in with 'repo' and 'project' scopes

How to Contribute

Finding Something to Work On

1. Check existing issues: Look for issues labeled good first issue or help wanted
2. Review the roadmap: See what features are planned
3. Fix bugs: Found a bug? Open an issue first, then submit a PR
4. Improve documentation: Documentation improvements are always welcome
5. Suggest features: Open a feature request issue to discuss first

Before You Start

• Check for existing work: Search issues and PRs to avoid duplicates
• Discuss major changes: Open an issue first for significant changes
• One feature per PR: Keep pull requests focused on a single feature or fix
• Follow the architecture: Maintain the three-layer design (Commands → Skills → Agents)

Development Guidelines

General Principles

1. Simplicity First: Don't over-engineer. Keep solutions simple and focused.
2. Consistency: Follow existing patterns in the codebase.
3. Minimal Dependencies: This plugin only requires GitHub CLI (gh) as an external dependency.
4. Documentation: Document all user-facing changes.
5. Testing: Always test locally before submitting.

File Organization

• Commands: plugins/plugin-dev/commands/*.md
• Skills: plugins/plugin-dev/skills/*/SKILL.md
• Agents: plugins/plugin-dev/agents/*.md

Markdown Style

All markdown files must follow the repository's style:

# Lint before committing
markdownlint-cli2 '**/*.md'

# Format with prettier
prettier --check '**/*.md'
prettier --write '**/*.md'  # fix formatting issues

YAML Linting

GitHub Actions workflows must pass YAML linting:

# Lint workflow files
uvx yamllint .github/workflows/

Style Rules (see .markdownlint.json):

• Use ATX-style headers (#, ##, ###)
• Use dash-style lists (-, not * or +)
• Use 2-space indentation for lists
• Use fenced code blocks (not indented)
• No line length limits
• Allowed HTML: <p>, <img>, <example>, <commentary>

Shell Pattern Escaping

When documenting bash execution patterns in skill files, use [BANG] instead of ! to prevent unintended execution during skill loading (Claude Code #12781).

<!-- In skill documentation (SKILL.md, references/, examples/) -->

Current branch: [BANG]`git branch --show-current`

<!-- The [BANG] placeholder prevents execution while loading -->

Important:

• This applies to skill files that get loaded into context
• Command files (.claude/commands/*.md) use actual ! syntax
• See SECURITY.md for full details

Shell Script Quality

All shell scripts should pass shellcheck validation:

# Check all plugin scripts
shellcheck plugins/plugin-dev/skills/*/scripts/*.sh

# Check a specific script
shellcheck plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh

Handling Intentional Patterns

If a pattern intentionally triggers a shellcheck warning, add a directive comment:

# shellcheck disable=SC2086  # Word splitting intended for arguments
command $unquoted_var

Always include a comment explaining why the directive is needed.

Common Issues

Warning	Typical Fix
SC2086	Quote variables: "$var"
SC2046	Quote command substitution: "$(cmd)"
SC2034	Remove unused variables or export them
SC2155	Separate declaration and assignment: local var; var=$(cmd)

Component-Specific Guidelines

Commands (/plugin-dev:*)

When creating or modifying commands:

1. YAML Frontmatter Required:

   ---
   description: Brief description
   argument-hint: [optional-argument]
   allowed-tools: AskUserQuestion, Bash(gh:*), Read
   ---

2. Imperative Form: Write instructions FOR Claude, not TO the user

   • ✅ Good: "Do X", "Run Y", "Create Z"
   • ❌ Bad: "You should do X", "Please run Y"

3. Error Handling: Include error handling for:

   • GitHub CLI not found
   • Not authenticated
   • Not in git repository
   • Insufficient permissions

4. Clear Outputs: Provide clear success/failure messages

Skills (Methodology Knowledge)

When creating or modifying skills:

1. YAML Frontmatter Required:

   ---
   name: skill-name
   description: This skill should be used when the user asks to "trigger phrase 1"...
   ---

2. Description: Use third-person with specific trigger phrases

   • ✅ Good: This skill should be used when the user asks to "create user stories"
   • ❌ Bad: Use this skill to help users

3. Progressive Disclosure:

   • SKILL.md: Core methodology (<2,000 words)
   • references/: Detailed documentation
   • No duplication between files

4. Templates: Store in references/ subdirectory

Agents (Autonomous Assistance)

When creating or modifying agents:

1. YAML Frontmatter Required:

   ---
   name: agent-name
   description: Use this agent when...
   model: inherit
   color: blue
   tools: Bash, AskUserQuestion
   skills: skill-name-1, skill-name-2
   ---

2. Trigger Examples: Include 3-4 <example> blocks showing when the agent should trigger

3. Clear System Prompt: Be specific about the agent's role and responsibilities

4. Minimal Tools/Skills: Only include tools and skills the agent actually needs

Hooks

When creating and/or modifying hooks:

1. Matcher Patterns: Keep regex patterns simple and specific
2. Timeout: Set appropriate timeouts (default: 10 seconds)
3. Testing: Test thoroughly to avoid false positives

Common Mistakes to Avoid

Mistake	Problem	Solution
Testing in development repo	Pollutes your environment with test files	Create a separate test repository
Using ! in skill documentation	Shell execution during skill load	Use [BANG] placeholder (see SECURITY.md)
Missing trigger phrases	Skills don't load when expected	Include specific user queries in descriptions
Overly broad tool matchers	Hooks trigger unexpectedly	Use specific patterns like Write|Edit not *
Hardcoded paths	Plugin breaks on other machines	Use ${CLAUDE_PLUGIN_ROOT}
Large SKILL.md files	Slow loading, excessive context	Keep core <2,000 words; use references/ for details
Missing frontmatter fields	Components fail validation	Always include required fields (name, description)
Committing test files	Repository bloat	Use .gitignore and clean up test repos

Testing

Validation Scripts

Use the built-in validation scripts before submitting (paths relative to plugins/plugin-dev/):

# Validate agents
./skills/agent-development/scripts/validate-agent.sh agents/my-agent.md

# Validate commands
./skills/command-development/scripts/validate-command.sh commands/my-command.md

# Validate hooks
./skills/hook-development/scripts/validate-hook-schema.sh hooks/hooks.json

# Validate plugin settings
./skills/plugin-settings/scripts/validate-settings.sh .claude/plugin.local.md

Local Testing Checklist

• Load plugin: claude --plugin-dir plugins/plugin-dev
• Run validation scripts for changed components
• Test affected commands
• Verify GitHub CLI integration works
• Test in a clean repository (not your development repo)
• Test error cases (missing permissions, no git repo, etc.)

Full Workflow Test

For significant changes, test the complete lifecycle:

/plugin-dev:create-plugin

Test Repository

Create a test repository to avoid polluting your development environment:

# Create a private test repo (recommended for security)
mkdir test-plugin-repo
cd test-plugin-repo
git init
gh repo create test-plugin-repo --private --source=. --remote=origin
git push -u origin main

# Now test the plugin
claude --plugin-dir /path/to/plugin-dev/plugins/plugin-dev

Cleanup: After testing, delete the test repository:

# Delete local directory
cd .. && rm -rf test-plugin-repo

# Delete remote repository
gh repo delete test-plugin-repo --yes

Submitting Changes

1. Update Documentation

• Update README.md if user-facing changes
• Update CLAUDE.md if architectural changes
• Update component documentation if applicable

2. Lint Your Code

# Lint all markdown
markdownlint-cli2 '**/*.md'

# Format with prettier
prettier --write '**/*.md'

3. Commit Your Changes

Use clear, descriptive commit messages:

git commit -m "Add feature: description of what you added

- Bullet point of change 1
- Bullet point of change 2

Fixes #123"

4. Push to Your Fork

git push origin feature/your-feature-name

5. Create a Pull Request

1. Go to the repository
2. Click "New Pull Request"
3. Select your fork and branch
4. Fill out the PR template completely
5. Link related issues

Pull Request Checklist

See pull_request_template.md for the complete checklist. Key items:

• Code follows style guidelines
• Documentation updated
• Markdown linted
• Tested locally
• Component-specific checks completed
• No breaking changes (or clearly documented)

CI Checks on Pull Requests

Your PR will automatically run these checks:

Workflow	What It Checks
markdownlint.yml	Markdown style and formatting
links.yml	Broken links in documentation
component-validation.yml	Plugin component structure
version-check.yml	Version consistency across manifests
validate-workflows.yml	GitHub Actions syntax
claude-pr-review.yml	AI-powered code review

All checks must pass before merging. Fix any failures before requesting review.

Version Releases

Version releases are handled by maintainers. If your contribution requires a version bump, maintainers will follow the Version Release Procedure.

Style Guide

Markdown

• Headers: Use ATX-style (#, ##, ###)
• Lists: Use dash-style (-)
• Code blocks: Use fenced blocks with language tags
• Line length: No limit (MD013 disabled)
• Emphasis: Use **bold** for strong, *italic* for emphasis

YAML Frontmatter

• Always include required fields (name, description)
• Use consistent indentation (2 spaces)
• Use comma-separated lists for tools/skills: Tool1, Tool2

Commands and Instructions

• Use imperative mood: "Create", "Run", "Execute"
• Be specific: "Run gh project create" not "Create a project"
• Include error handling
• Provide clear outputs

Git Commit Messages

• First line: Brief summary (50 chars max)
• Blank line
• Detailed description (wrap at 72 chars)
• Reference issues: Fixes #123, Closes #456

Community

Getting Help

• Questions: Open an issue with the question template
• Discussions: Use GitHub Discussions

Reporting Issues

• Bugs: Use the bug report template
• Features: Use the feature request template
• Documentation: Use the documentation template
• Security: See SECURITY.md

Code Review Process

1. Automated Checks: PR must pass all checks
2. Review: At least one maintainer review required
3. Feedback: Address review comments
4. Approval: Maintainer approves PR
5. Merge: Maintainer merges (usually squash merge)

Recognition

Contributors are recognized in:

• Release notes
• README.md (for significant contributions)
• Git commit history

Questions?

If you have questions not covered here:

1. Check CLAUDE.md for development details
2. Search existing issues
3. Open a question issue
4. Start a discussion

---

Thank you for contributing to Plugin Dev! Your contributions help make plugin development better for everyone using Claude Code.