Skip to content

Contributing to Talent Factory Claude Plugins

Thank you for your interest in contributing to our Claude Code plugins! We welcome contributions from the community and are grateful for your support.

🎯 How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates.

When filing a bug report, please include:

  • A clear and descriptive title
  • Steps to reproduce the issue
  • Expected behavior vs. actual behavior
  • Claude Code version
  • Operating system and version
  • Plugin version(s) affected
  • Any relevant error messages or logs

Suggesting Enhancements

We love to hear your ideas! Enhancement suggestions are tracked as GitHub issues.

When suggesting an enhancement, please include: - A clear and descriptive title - Detailed description of the proposed feature - Use cases and benefits - Any relevant examples or mockups - Which plugin(s) would be affected

Pull Requests

We actively welcome your pull requests! Here's how to contribute code:

🔧 Development Setup

Prerequisites

  • Claude Code installed (Installation Guide)
  • Git installed
  • Basic understanding of Claude Code plugin structure

Getting Started

  1. Fork the repository

    Bash
    1
2
3
    # Click "Fork" on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/claude-plugins.git
cd claude-plugins

  2. Create a feature branch

    Bash
    1
2
3
    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  3. Test your changes locally

    Bash
    1
2
3
4
5
    # Test a specific plugin
claude --plugin-dir ./plugins/PLUGIN-NAME

# Test all plugins
claude --plugin-dir .

📝 Contribution Guidelines

Branch Naming Convention

  • feature/ - New features (e.g., feature/add-python-tutor)
  • fix/ - Bug fixes (e.g., fix/commit-validation-error)
  • docs/ - Documentation updates (e.g., docs/update-installation-guide)
  • refactor/ - Code refactoring (e.g., refactor/simplify-pr-template)

Commit Message Format

We follow Conventional Commits:

Text Only
1
2
3
4
5
type(scope): subject

body (optional)

footer (optional)

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

Text Only
1
2
3
feat(education): add Python tutor agent
fix(git-workflow): resolve commit validation error
docs(readme): update installation instructions

Code Style

  • Use clear, descriptive names for commands and agents
  • Follow existing plugin structure and conventions
  • Include comprehensive documentation in command/agent files
  • Add examples where appropriate
  • Keep commands focused and single-purpose

Plugin Structure

When creating or modifying plugins, follow this structure:

Text Only
1
2
3
4
5
6
7
8
plugins/your-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── commands/
│   └── your-command.md      # Command definitions
├── agents/
│   └── your-agent.md        # Agent definitions (optional)
└── README.md                # Plugin documentation

Testing Your Changes

Before submitting a PR:

  1. Test the plugin locally

    Bash
    1
    claude --plugin-dir ./plugins/YOUR-PLUGIN

  2. Verify all commands work

  3. Test each command in Claude Code
  4. Check for errors or unexpected behavior

  5. Verify documentation is accurate

  6. Run validation (if available)

    Bash
    1
2
    /check-commands  # Using core plugin
/check-agents    # Using core plugin

  7. Check documentation

  8. Ensure README is updated
  9. Verify examples are correct
  10. Check for typos and clarity

🚀 Submitting a Pull Request

  1. Push your changes

    Bash
    1
    git push origin feature/your-feature-name

  2. Create a Pull Request

  3. Go to the repository
  4. Click "New Pull Request"
  5. Select your fork and branch

  6. Fill out the PR template completely

  7. PR Requirements

  8. Clear description of changes
  9. Reference related issues (e.g., "Fixes #123")
  10. All tests pass (if CI/CD is configured)
  11. Documentation is updated

  12. Follows code style guidelines

  13. Review Process

  14. A maintainer will review your PR
  15. Address any requested changes
  16. Once approved, your PR will be merged

🔒 Branch Protection

Important: The main and develop branches are protected to ensure code quality and maintain a clean history.

Branch Access Rules

Main Branch

  • Purpose: Production-ready code, stable releases
  • Access: Pull Requests only (no direct commits)
  • Requirements:
  • At least 1 approval from a maintainer
  • All CI/CD checks must pass
  • Must be up-to-date with base branch
  • No merge conflicts

Develop Branch

  • Purpose: Integration branch for ongoing development
  • Access:
  • Maintainer (Daniel Senften) only: Direct commits allowed
  • All other contributors: Pull Requests required
  • Requirements for PRs:
  • At least 1 approval from a maintainer
  • All CI/CD checks must pass
  • Must be up-to-date with base branch
  • Branch naming convention must be followed

Why These Rules?

  1. Code Quality: All changes are reviewed before merging
  2. Traceability: Every change has a documented reason (PR description)
  3. CI/CD Integration: Automated tests catch issues early
  4. Collaboration: PRs facilitate discussion and knowledge sharing
  5. Reversibility: Easy to revert changes if needed

Automated Protection

Our CI/CD pipeline enforces these rules automatically:

  • Validates branch naming conventions
  • Checks commit message format
  • Runs plugin validation tests
  • Scans for security issues
  • Ensures documentation is updated

Note: Even if you have write access to the repository, please respect these rules. They exist to protect the project and maintain quality for all users.

📚 Additional Resources

💬 Questions?

🙏 Thank You!

Your contributions make this project better for everyone. We appreciate your time and effort!

Maintained by: Talent Factory GmbH
License: MIT