Contributing to claude-ai-music-skills

Contributing to claude-ai-music-skills

Thank you for contributing! This document explains our development workflow.

Branch Model

We use a **two-branch model** with `develop` as the integration branch and `main` as the stable release branch:

• develop — active development, receives feature branch PRs, version tagged with -dev suffix (e.g., 0.62.0-dev)
• main — stable releases only, receives merges from develop when ready to release

CI runs on pushes to `develop` and on PRs into both branches. Direct pushes to `main` skip CI (already validated by the PR gate).

**Plugin distribution channels** (both use `marketplace.json`, branch separation handles the split):

• Stable: /plugin marketplace add bitwize-music-studio/claude-ai-music-skills (from main)
• Dev: /plugin marketplace add https://github.com/bitwize-music-studio/claude-ai-music-skills.git#develop

Development Workflow

We use a **PR-based workflow** with the following process:

1. Create a Feature Branch

# Create branch from develop
git checkout develop
git pull origin develop
git checkout -b feat/your-feature-name  # or fix/, docs/, chore/

**Branch naming conventions:**

• feat/ - New features
• fix/ - Bug fixes
• docs/ - Documentation changes
• chore/ - Maintenance tasks

2. Make Your Changes

Follow the existing code patterns and documentation style.

**Key files to update:**

• If adding a skill: Create /skills/your-skill/SKILL.md
• If changing workflow: Update CLAUDE.md
• If user-facing: Update README.md
• Always: Update CHANGELOG.md under "Unreleased"

Adding a New Skill - Complete Checklist

When adding a new skill, you MUST update all of these files:

**Required (skill won't work without these):**

• Create /skills/your-skill/SKILL.md with skill documentation
• Add entry to CLAUDE.md skills table (alphabetically in correct category)
• Add entry to skills/help/SKILL.md in appropriate category
• Add entry to skills/help/SKILL.md Common Workflows section (if applicable)
• Update CHANGELOG.md under "Unreleased" → "Added"

**Recommended:**

• Add entry to reference/SKILL_INDEX.md (alphabetical table + decision tree + skill categories)
• Add entry to reference/model-strategy.md under appropriate model tier
• Add quick tip to skills/help/SKILL.md Quick Tips section (if relevant)
• Update workflow diagram in CLAUDE.md (if part of main workflow)
• Add to Album Completion Checklist in CLAUDE.md (if part of release)
• Add reference docs in /reference/ if complex
• Update README.md Skills Reference tables (add to appropriate section: Core Production, Research, Quality Control, Release, or Setup & Maintenance)

**Testing:**

• Run /bitwize-music:test all to ensure no regressions
• Test skill invocation: /bitwize-music:your-skill
• Verify skill appears in /bitwize-music:help output
• Check skill in skills table works as expected

**