/update-component-reference

name: update-component-reference
description: This skill should be used when the user wants to add components (commands, agents, skills, hooks, or MCP servers) to the Component Reference section of the website.

Update Component Reference Skill

Add documentation for Claude Code components (commands, agents, skills, hooks, MCP servers) to the website's Component Reference section.

When to Use

Use this skill when the user requests to:

• Add a new component to the Component Reference documentation
• Document a newly created command, agent, skill, hook, or MCP server
• Update component documentation in the reference section

Prerequisites Checklist

Before documenting a component, ensure:

1. **Component exists** in the appropriate plugin directory:

• Commands: `plugins/handbook/commands/{name}.md`
• Agents: `plugins/handbook/agents/{name}.md`
• Skills: `plugins/handbook/skills/{name}/SKILL.md`
• Hooks: `plugins/{plugin-name}/hooks/hooks.json` and hook scripts
• MCP Servers: `plugins/{plugin-name}/.mcp.json`

2. **For skills only**: Component is registered in plugin.json:

   {
     "skills": [
       "./skills/skill-creator",
       "./skills/{new-skill-name}"
     ]
   }

3. **Verify plugin name**: Check `.claude-plugin/plugin.json` for the badge (e.g., "handbook", "handbook-dotnet")

Implementation Process

Step 1: Determine Target Directory

Component documentation goes in: `website/docs/component-reference/{type}/`

• Commands → `website/docs/component-reference/commands/`
• Agents → `website/docs/component-reference/agents/`
• Skills → `website/docs/component-reference/skills/`
• Hooks → `website/docs/component-reference/hooks/`
• MCP Servers → `website/docs/component-reference/mcp-servers/`

All category directories and `_category_.json` files already exist for these types.

Step 2: Determine sidebar_position

Read existing `.mdx` files in the target directory to find the highest `sidebar_position` and add 1.

Example:

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

Step 3: Create Component Documentation File

**Filename convention**: Use kebab-case matching the component name

• Command `/commit` → `commit.mdx`
• Agent `@backend-architect` → `backend-architect.mdx`
• Skill `skill-creator` → `skill-creator.mdx`
• Hook `csharp-formatter` → `csharp-formatter.mdx`
• MCP Server `context7` → `context7.mdx`

Step 4: Write MDX Content

Use the appropriate template based on component type:

Commands Template

---
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

Agents Template

---
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

Skills Template

---
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

Hooks Template

---
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 }

Use Cases

• Bullet points

Installation

Setup notes.

Related

• Links

#### 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 }

Coverage

• Bullet list

Example Usage

"Example query"

Installation

Setup notes.

Related

• Links

### 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