# Creating Components - Quick Reference

Best practices for building Claude Code extensions in this marketplace.

## Component Types

| Need | Use | Where |
|------|-----|-------|
| User-invocable action | **Skill** | `plugins/<domain>/skills/` |
| Slash command | **Command** | `plugins/<domain>/commands/` |
| System hook | **Hook** | `plugins/<domain>/hooks/` |
| Bundle & distribute | **Plugin** | Root of plugin directory |
| Library/reference | **Reference file** | `skills/<skill>/references/` |

## Key Patterns

**SKILL.md frontmatter**:
```yaml
---
name: skill-name
description: WHAT it does. WHEN to use. NOT FOR anti-patterns. (max 1024 chars)
---
```

**Command.md frontmatter**:
```yaml
---
name: /command-name
triggers: ["alias1"]
prompt: System prompt here
allowed-tools: [read, edit, bash]
---
```

**File size limits**:
- SKILL.md: 250 lines max (use `references/` for more)
- Command.md: 100 lines max
- Reference file: 250 lines max
- Split if larger

## Reference Routing Pattern

When creating a skill with references/, explicitly route from master SKILL.md with loading intent:

### ✅ GOOD: Explicit routing with intent

```markdown
# Skill Title

## Core Workflow
[Main content]

## Advanced Features

For production-grade optimization patterns, see [references/performance.md](references/performance.md)
- Load this when you need to handle high-volume scenarios or optimize for latency
```

### ❌ LESS GOOD: References exist but no routing

```markdown
# Skill Title

[Content without mentioning references/]
```

**Pattern: Every reference needs**:
1. Explicit link from master SKILL.md
2. "Load this when you need to..." description
3. One level deep (avoid deeply nested subdirectories)

**Example from effectts skill** (model):
```markdown
## What Are You Building?

| Domain | When to Use | Reference |
|--------|-------------|-----------|
| **State Management** | React apps with effect-atom | [references/effect-atom-reference.md](references/effect-atom-reference.md) |
```

This pattern explicitly lists what each reference covers and when to read it.

## Code Quality Gates

- [ ] Clear, focused purpose (one per component)
- [ ] Description follows WHAT/WHEN/NOT-FOR pattern
- [ ] CHANGELOG.md updated
- [ ] No hardcoded paths (use repo-relative references or `${CLAUDE_PLUGIN_ROOT}`)
- [ ] Examples included
- [ ] Tested with headless execution
- [ ] All files < 250 lines

## References

- **Full patterns**: See other reference files in this directory
- **CLI docs**: [Claude Code Plugin Development](https://modelcontextprotocol.io/docs)
- **Plugin updates**: `plugin-updates.md`
- **Command testing**: `command-testing.md`

*Last updated: 2025-12-20*
