CLAUDE.md · mhattingpete/claude-skills-marketplace

Sections

1. 🎯 Repository Context
2. 🏗️ Plugin Structure Standards
3. 🎨 Skill Design Principles
4. 🔨 Creating a New Skill
5. 📚 Reference Materials
6. 🤖 Creating Agents
7. 🎯 Quality Standards
8. 📦 Version Management
9. 🔄 Workflow for Updates
10. 🧪 Testing Checklist
11. 💡 Skill Ideas & Patterns
12. 🎓 Learning from Existing Skills
13. 🚀 When Working on This Repository
14. 📋 Quick Reference
15. 🎁 Remember

First lines (shown under the repo's Apache-2.0 license)

# Claude Code Instructions for Skills Marketplace Development

**Repository:** claude-skills-marketplace
**Purpose:** Development guidelines for creating high-quality Claude Code skills and plugins

---

## 🎯 Repository Context

This is the **Claude Skills Marketplace** - a collection of reusable skills and plugins for Claude Code. When working in this repository, you are helping develop skills that will be used by many developers.

### Current Plugins

1. **engineering-workflow-skills** (v1.1.0)
   - feature-planning, test-fixing, git-pushing, review-implementing
   - plan-implementer agent

2. **visual-documentation-skills** (v1.0.0)
   - visual-html-creator for stunning HTML documentation

3. **productivity-skills** (v1.0.0)
   - conversation-analyzer, code-auditor, project-bootstrapper, codebase-documenter

---

## 🏗️ Plugin Structure Standards

### Required Directory Structure

```
{plugin-name}-plugin/
├── .claude-plugin/
│   └── plugin.json              # REQUIRED: Plugin metadata ONLY (no skills array)
├── skills/                      # Skills directory (auto-discovered)
│   └── {skill-name}/
│       ├── SKILL.md             # REQUIRED: Skill specification
│       ├── references/          # OPTIONAL: Reference materials (markdown)
│       │   └── *.md             # Additional context/guides
│       └── scripts/             # OPTIONAL: Helper scripts
│           └── *.py             # Python scripts, shell scripts, etc.
├── agents/                      # OPTIONAL: Agents directory (auto-discovered)
│   └── {agent-name}/
│       └── AGENT.md             # Agent specification
├── commands/                    # OPTIONAL: Commands directory (auto-discovered)
│   └── {command-name}.md
├── README.md                    # REQUIRED: Plugin documentation
├── CHANGELOG.md                 # RECOMMENDED: Version history
└── EXAMPLES.md                  # RECOMMENDED: Usage examples
```

**CRITICAL: Skills are auto-discovered!**
- Skills MUST be in `skills/` subdirectory at plugin root
- Skills are automatically discovered - NO listing in plugin.json
- plugin.json contains ONLY metadata (name, version, description, author)
- Same applies to agents/ and commands/ - all auto-discovered

**Directory purposes:**
- `skills/` - All skills (auto-discovered from SKILL.md files)
- `agents/` - All agents (auto-discovered from AGENT.md files)
- `commands/` - All commands (auto-discovered from .md files)
- `references/` - Markdown documentation, guides, best practices
- `scripts/` - Executable scripts (Python, shell, etc.) that skills can use

### Critical Files

#### 1. `.claude-plugin/plugin.json`

**Location matters!** Must be in `.claude-plugin/` subdirectory, not at root.

```json
{
  "name": "example-skills",
  "version": "1.0.0",
  "description": "Clear, concise description of what the plugin provides",
  "author": {
    "name": "author-name"
  }
}
```

**Key points:**
- **ONLY metadata** - name, version, description, author
- **NO skills array** - skills are auto-discovered from skills/ directory
- **NO agents array** - agents are auto-discovered from agents/ directory
- **NO commands array** - commands are auto-discovered from commands/ directory
- Keep it simple - just plugin metadata!

#### 2. `SKILL.md`

Every skill MUST have a SKILL.md file. This is the instruction set for Claude.

**Required sections:**

```markdown
# {Skill Name}

## Purpose
Clear statement of what this skill does and why it exists.

## When to Use
List of scenarios where this skill is appropriate.

**Activation phrases:**
- "phrase that triggers this skill"
- "another trigger phrase"
- "third example"

## What It Does
Detailed explanation of the skill's workflow:
1. First step
2. Second step
3. etc.

## Approach
How the skill should approach the task, including:
- Analysis strategy
- Tool usage patterns
- Decision-making criteria
- Error handling

## Example Interaction
```
User: "example request"

Skill:
1. Does X
2. Asks Y
3. Implements Z
```

## Tools Used
- **ToolName**: Why and when to use it
- **AnotherTool**: Purpose

## Success Criteria
How to know when the skill has succeeded:
- Criterion 1
- Criterion 2

## Integration
How this skill works with other skills (if applicable).
```

**Best practices for SKILL.md:**
- Be specific about activation phrases
- Include concrete examples
- Explain the "why" not just the "what"
- Mention tool usage patterns
- Define success criteria clearly
- Use realistic example interactions

#### 3. `README.md`

Plugin README should be user-facing documentation:

```markdown
# {Plugin Name}

Brief description of what the plugin provides.