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:

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:

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:

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: This repository uses trunk-based development — main is the single long-lived branch, protected to ensure code quality and a clean history. All work happens on short-lived branches that merge back into main via Pull Request.

Branch Access Rules¶

Main Branch¶

• Purpose: The single source of truth and live marketplace source
• Access: Pull Requests only (no direct commits)
• Requirements:
• All CI/CD checks must pass
• Must be up-to-date with main
• No merge conflicts
• Branch naming convention must be followed
• Review recommended; the solo maintainer (Daniel Senften) may self-approve and merge own PRs

Feature Branches¶

• Purpose: All new work — features, fixes, documentation, refactors
• Base & target: Created from main, merged back into main
• Naming: feature/, fix/, docs/, refactor/ (see naming convention above)

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¶

• Plugin Development Guide
• Claude Code Documentation
• Conventional Commits

💬 Questions?¶

• Open a Discussion
• Ask in your Pull Request
• Email: support@talent-factory.ch

🙏 Thank You!¶

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

Maintained by: Talent Factory GmbH
License: MIT