# Contributing to Claude Skills Marketplace Thank you for contributing! This guide helps you add plugins, skills, and improvements to the marketplace. ## Types of Contributions 1. **Add skills to existing plugins** - Extend claude-code or claude-skills 2. **Create new plugins** - Package related skills together 3. **Improve existing skills** - Refine content, fix bugs, add examples 4. **Update documentation** - Improve guides and READMEs ## Before You Start 1. **Use the claude-skills plugin** - Get guidance on skill creation 2. **Review existing plugins** - Check claude-code and claude-skills-plugin 3. **Test thoroughly** - See [TESTING.md](./TESTING.md) ## Adding a Skill to an Existing Plugin ### Option 1: Add to claude-code Plugin Add Claude Code-specific skills (features, tools, workflows): ```bash # 1. Create skill directory cd claude-code/skills mkdir my-claude-code-skill # 2. Create SKILL.md cat > my-claude-code-skill/SKILL.md << 'EOF' --- name: My Claude Code Feature description: [Specific description with trigger scenarios] --- # Content here EOF # 3. Update plugin README vim claude-code/README.md # Add your skill to the "What's Included" section ``` **Best for:** - Claude Code features (like our existing 5 skills) - Development workflows - Tool integrations ### Option 2: Add to claude-skills Plugin Add skill-creation guidance (templates, patterns, best practices): ```bash # 1. Create skill directory cd claude-skills-plugin/skills mkdir my-skill-pattern # 2. Create SKILL.md # Follow claude-skills format (see existing skill) # 3. Update plugin README ``` **Best for:** - New skill templates - Skill-creation patterns - Meta-guidance on skills ## Creating a New Plugin For a collection of related skills that don't fit existing plugins: ### 1. Create Plugin Structure ```bash # Create plugin directory mkdir my-plugin # Create required directories mkdir -p my-plugin/.claude-plugin mkdir -p my-plugin/skills # Optional: commands, agents, hooks mkdir -p my-plugin/commands mkdir -p my-plugin/agents mkdir -p my-plugin/hooks ``` ### 2. Create plugin.json ```bash cat > my-plugin/.claude-plugin/plugin.json << 'EOF' { "name": "my-plugin", "description": "Clear description of plugin purpose", "version": "1.0.0", "author": { "name": "Your Name", "email": "you@example.com" }, "keywords": [ "keyword1", "keyword2" ] } EOF ``` **Required fields:** - `name` - Lowercase, kebab-case identifier - `description` - Clear, concise purpose - `version` - Semantic versioning (1.0.0) - `author.name` - Creator name **Optional fields:** - `author.email` - Contact email - `author.url` - Website or profile - `repository` - Git repository info - `license` - License identifier - `keywords` - Search/discovery terms ### 3. Add Skills to Plugin ```bash # Create skill directory mkdir my-plugin/skills/my-skill # Create SKILL.md with frontmatter cat > my-plugin/skills/my-skill/SKILL.md << 'EOF' --- name: Skill Name description: [Specific description] --- # Skill content EOF ``` ### 4. Create Plugin README ```bash cat > my-plugin/README.md << 'EOF' # My Plugin Brief description. ## What's Included List of skills/features ## Installation ```bash /plugin install my-plugin@claude-skills ``` ## Usage Examples of how to use [More sections...] EOF ``` ### 5. Update Marketplace Manifest ```bash # Edit .claude-plugin/marketplace.json vim .claude-plugin/marketplace.json ``` Add your plugin: ```json { "plugins": [ { "name": "my-plugin", "source": "./my-plugin", "description": "Brief plugin description" } ] } ``` ### 6. Test Plugin Installation ```bash # Test local installation /plugin install /path/to/Skills/my-plugin@local # Verify skills load # Try triggering scenarios ``` ## Skill Creation Guidelines ### Required: SKILL.md Structure ```yaml --- name: Skill Name (max 64 chars) description: Specific description with triggers (max 1024 chars) --- # Skill Name ## When to Use This Skill Use this skill when: - [Primary scenario] - [Secondary scenario] Do NOT use this skill for: - [Confusion case] ## Quick Start [Minimal example] ## Core Workflows [Step-by-step guides] ## Examples [Concrete examples] ``` ### Writing Effective Descriptions **Template:** ``` [Action] [domain/task] [with/for] [capabilities]. Use when [trigger scenario]. [Optional: PROACTIVELY/MUST BE USED if needed] ``` **Good Examples:** ```yaml # Specific, clear triggers description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests. # Domain-specific description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use when memory isn't loading, context is bloated, or organizing memory hierarchy. ``` **Bad Examples:** ```yaml # Too vague description: Helps with development # No triggers description: Python tools and utilities ``` ### Progressive Disclosure **Layer 1: Metadata (100 tokens)** - Skill name and description in frontmatter - Triggers skill selection **Layer 2: SKILL.md (2000-5000 tokens)** - Core workflows and common examples - Loaded when skill activates **Layer 3: Additional Files (on-demand)** - Detailed docs in separate .md files - Scripts, templates, references - Loaded only when needed ### Content Best Practices **DO:** - Be specific, not vague - Use bullet points, not paragraphs - Include concrete, working examples - Provide step-by-step workflows - Add troubleshooting sections - Test trigger scenarios **DON'T:** - Include sensitive data (API keys, credentials) - Use generic advice ("write good code") - Create novel-length content - Duplicate information - Skip testing ## Quality Checklist Before submitting: ### Metadata - [ ] Name ≤ 64 characters - [ ] Description ≤ 1024 characters - [ ] Description includes specific triggers - [ ] YAML frontmatter is valid ### Content - [ ] "When to Use This Skill" section present - [ ] At least one concrete example - [ ] Examples are runnable/testable - [ ] File references are accurate - [ ] No sensitive data hardcoded ### Testing - [ ] Skill triggers on target scenarios - [ ] Doesn't trigger on unrelated scenarios - [ ] Examples work as documented - [ ] No conflicts with existing skills ### Documentation - [ ] Plugin README updated - [ ] Marketplace manifest updated (if new plugin) - [ ] Clear installation instructions - [ ] Usage examples provided ## Testing Your Contribution See [TESTING.md](./TESTING.md) for: - Trigger accuracy testing - Content quality validation - Token efficiency measurement - Team collaboration testing Quick test: ```bash # 1. Install locally /plugin install /path/to/your-plugin@local # 2. Test trigger scenarios # Ask questions that should trigger the skill # 3. Test exclusion scenarios # Ask questions that should NOT trigger # 4. Verify quality # Review Claude's responses for accuracy ``` ## Submission Process ### For Small Changes (Skills to Existing Plugins) 1. Create skill in appropriate plugin 2. Update plugin README 3. Test locally 4. Submit PR with: - Skill files - Updated README - Test results ### For New Plugins 1. Create complete plugin structure 2. Update marketplace.json 3. Create plugin README 4. Test installation and usage 5. Submit PR with: - Full plugin directory - Updated marketplace.json - Documentation - Test results ## Common Patterns ### Plugin Organization ``` my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ # Related skills grouped together │ ├── skill-1/ │ ├── skill-2/ │ └── skill-3/ ├── commands/ # Optional: slash commands ├── agents/ # Optional: subagent configs ├── hooks/ # Optional: automation hooks └── README.md ``` ### Skill Naming Conventions **For Claude Code features:** - `claude-[feature]` (e.g., claude-plugins) **For domain-specific:** - `[domain]-[purpose]` (e.g., python-testing, api-documentation) **For meta/general:** - `[category]-[action]` (e.g., skill-creator, code-reviewer) ### Version Bumping Follow semantic versioning: ```json { "version": "1.2.3" } ``` - **Major (1.x.x)**: Breaking changes - **Minor (x.2.x)**: New features, backward compatible - **Patch (x.x.3)**: Bug fixes Update version in plugin.json when: - Adding new skills → Minor - Changing skill structure → Major - Fixing bugs → Patch ## Example: Adding a Skill ### Scenario: Add "claude-mcp" skill ```bash # 1. Navigate to plugin cd claude-code/skills # 2. Create skill mkdir claude-mcp # 3. Create SKILL.md cat > claude-mcp/SKILL.md << 'EOF' --- name: Claude Code MCP Servers description: Configure and troubleshoot Model Context Protocol servers for Claude Code. Use when setting up MCP servers, debugging connections, or integrating external tools. --- # Claude Code MCP Server Management ## When to Use This Skill [Content here...] EOF # 4. Update plugin README vim ../README.md # Add claude-mcp to "What's Included" # 5. Bump version in plugin.json vim ../.claude-plugin/plugin.json # Change: "version": "1.0.0" → "1.1.0" # 6. Test /plugin install /path/to/Skills/claude-code@local # Test trigger scenarios # 7. Submit PR ``` ## Security Considerations ### Never Include - API keys, tokens, or credentials - Personal identifying information - Proprietary code without permission - Hardcoded paths to user-specific locations - Malicious scripts or commands ### Always Review - External dependencies (trusted sources only) - File system access patterns - Network requests - Bash commands in examples ## Getting Help - **Skill creation guidance** - Use claude-skills plugin - **Plugin structure questions** - Use claude-plugins skill - **Testing help** - See TESTING.md - **Questions** - Open an issue ## Resources - [Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) - [Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins) - [claude-skills Plugin](./claude-skills-plugin/README.md) - [claude-code Plugin](./claude-code/README.md) --- **Thank you for contributing!** Your skills help the entire Claude community work more effectively.