Update Component Reference

grep -h "sidebar_position:" website/docs/component-reference/skills/*.mdx | sort -n

---
title: "/command-name"
sidebar_position: N
---

import CommandNameSource from '!!raw-loader!../../../../plugins/handbook/commands/command-name.md'
import CodeBlock from '@theme/CodeBlock';

# Use `/command-name`

<span className="badge badge--handbook">handbook</span>

Brief description of what this command does (1-2 sentences).

More detailed explanation of the command's purpose and benefits.

## Command Specification

<CodeBlock language="markdown">
{CommandNameSource}
</CodeBlock>

## Additional sections as needed
- Example usage
- Tips and tricks
- Related commands

---
title: "@agent-name"
sidebar_position: N
---

import AgentNameSource from '!!raw-loader!../../../../plugins/handbook/agents/agent-name.md'
import CodeBlock from '@theme/CodeBlock';

# Use `@agent-name` agent

<span className="badge badge--handbook">handbook</span>

Brief description of what this agent specializes in (1-2 sentences).

More detailed explanation of the agent's capabilities and when to use it.

## Agent Specification

<CodeBlock language="markdown">
{AgentNameSource}
</CodeBlock>

## Additional sections as needed
- Key strengths
- Example use cases
- Related agents

---
title: "skill-name"
sidebar_position: N
---

import SkillNameSource from '!!raw-loader!../../../../plugins/handbook/skills/skill-name/SKILL.md'
import CodeBlock from '@theme/CodeBlock';

# Use `skill-name` skill

<span className="badge badge--handbook">handbook</span>

Brief description of what this skill provides (1-2 sentences).

More detailed explanation of the skill's purpose and capabilities.

## When to Use This Skill

Use the `skill-name` skill when you want to:

- Primary use case
- Secondary use case
- Additional scenarios

## Skill Specification

<CodeBlock language="markdown">
{SkillNameSource}
</CodeBlock>

## Additional sections as needed
- Key concepts
- Example workflows
- Related skills

---
title: "Hook Name"
sidebar_position: N
---

# Hook Name

<span className="badge badge--{plugin-name}">{plugin-name}</span>

Brief description (1-2 sentences).

## Configuration

```json
{ hook config from hooks.json }

#### MCP Servers Template

```mdx
---
title: "server-name"
sidebar_position: N
---

# Server Name MCP Server

<span className="badge badge--{plugin-name}">{plugin-name}</span>

Brief description (1-2 sentences).

## Configuration

```json
{ config from .mcp.json }

"Example query"

### Step 5: Verify Import Paths (Commands, Agents, Skills Only)

**Note**: Hooks and MCP Servers show configuration directly (no raw-loader imports needed).

For commands, agents, and skills, double-check the raw-loader import path:

- Commands: `'!!raw-loader!../../../../plugins/handbook/commands/{name}.md'`
- Agents: `'!!raw-loader!../../../../plugins/handbook/agents/{name}.md'`
- Skills: `'!!raw-loader!../../../../plugins/handbook/skills/{name}/SKILL.md'` ⚠️ Note the `/SKILL.md` suffix

The path goes up 4 directories (`../../../../`) from the `.mdx` file to reach the repo root.

## Common Pitfalls

1. **Forgetting plugin.json registration for skills**
   - Skills MUST be in plugin.json or they won't be available
   - Commands, agents, hooks, and MCP servers are auto-discovered

2. **Incorrect import paths**
   - Skills use `/SKILL.md` suffix: `skills/{name}/SKILL.md`
   - Commands and agents use `.md` directly: `commands/{name}.md`
   - Hooks and MCP servers don't use raw-loader (show config directly)

3. **Wrong relative path depth (commands, agents, skills only)**
   - Always use 4 levels up: `../../../../`
   - Path starts from the `.mdx` file location

4. **Inconsistent naming**
   - File names should match component names exactly (kebab-case)
   - Title in frontmatter should include prefix (`/` for commands, `@` for agents)

5. **Wrong plugin badge**
   - Badge class follows pattern: `badge--{plugin-name}`
   - Badge text is the plugin name (e.g., "handbook", "handbook-dotnet")

## Quick Reference

### Import Variable Naming Convention (Commands, Agents, Skills)
Match the component name in PascalCase + "Source":
- `commit.md` → `CommitCommandSource`
- `backend-architect.md` → `BackendArchitectAgentSource`
- `skill-creator/SKILL.md` → `SkillCreatorSource`

**Note**: Hooks and MCP servers don't use imports.

### Badge
Badge format: `<span className="badge badge--{plugin-name}">{plugin-name}</span>`

Examples:
- handbook: `<span className="badge badge--handbook">handbook</span>`
- handbook-dotnet: `<span className="badge badge--handbook-dotnet">handbook-dotnet</span>`

## Adding a New Plugin

When documenting components from a **new plugin**, also update:

1. **Badge CSS**: Add style to `website/src/css/custom.css` (pick unique color)
2. **Plugin index**: Add entry to `website/docs/plugins.md` (both main list and Direct Installation section)

## Example Workflow

**User**: "Add the new @pair-programmer agent to the documentation"

1. **Verify** component exists: `plugins/handbook/agents/pair-programmer.md` ✓
2. **Check** it's an agent (auto-discovered, no plugin.json needed) ✓
3. **Find** next sidebar_position in `website/docs/component-reference/agents/`
4. **Create** `website/docs/component-reference/agents/pair-programmer.mdx`
5. **Write** content using agent template
6. **Import** using: `'!!raw-loader!../../../../plugins/handbook/agents/pair-programmer.md'`
7. **Verify** documentation renders correctly