Skip to main content

Add Content Tab Skill Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Create a /add-content-tab Claude Code slash command that lets the content team create content.md files for existing folder-based components and patterns.

Architecture: Single skill file (.claude/commands/add-content-tab.md) that validates the target folder exists, checks if content.md already exists, asks the user about template type, and creates the file. No infrastructure changes — the existing plugin and AutoDocTabs already detect and render content.md automatically.

Tech Stack: Claude Code slash command (Markdown skill file)


File Structure​

FileActionResponsibility
.claude/commands/add-content-tab.mdCreateThe slash command — all logic lives here

No other files need modification. The doc-tabs-plugin.js already scans for content.md, AutoDocTabs already lazy-loads it, TAB_CONFIG already includes content, and docusaurus.config.ts already excludes */content.md from indexing.


Task 1: Create the slash command skill file​

Files:

  • Create: .claude/commands/add-content-tab.md

  • Step 1: Create the skill file

Create .claude/commands/add-content-tab.md with the following content:

# Add Content Tab

You are adding a content guidelines tab (`content.md`) to an existing Naos Design System component or pattern documentation page.

## Input

- **$ARGUMENTS** — expects: `<ComponentOrPatternName>`
- Accepts kebab-case (`info-card`), PascalCase (`InfoCard`), or lowercase (`infocard`)
- If no arguments provided, ask the user: "Which component or pattern needs a content tab?"

## Step 1: Derive Name Variants

From the input name, derive:
- **kebab**: `info-card` (folder name) — insert hyphens before uppercase letters and lowercase everything
- **pascal**: `InfoCard` (display title) — capitalize first letter of each segment

Examples:
- `InfoCard` → kebab: `info-card`, pascal: `InfoCard`
- `info-card` → kebab: `info-card`, pascal: `InfoCard`
- `infocard` → kebab: `infocard`, pascal: `Infocard`
- `date-picker` → kebab: `date-picker`, pascal: `DatePicker`

## Step 2: Locate the Documentation Folder

Search for the folder in this order:

1. Check `docs/components/<kebab>/index.md` — if it exists, this is a **component**
2. Check `docs/patterns/<kebab>/index.md` — if it exists, this is a **pattern**

**If neither exists**, report an error and stop:

> "No folder-based documentation found for `<kebab>`.
>
> - For components: run `/generate-component-doc <Name>` first
> - For patterns: run `/generate-pattern-doc <Name>` first
>
> This command only works with folder-based docs (those with an `index.md` and separate tab files)."

**If a single-file component exists** (e.g., `docs/components/<kebab>.md` without a folder), report:

> "Found `docs/components/<kebab>.md` but it's a single-file component. This command only works with folder-based docs. Convert it to a folder structure first, or use `/generate-component-doc <Name>` to create a new folder-based version."

## Step 3: Check if `content.md` Already Exists

Check if `<folder>/content.md` exists.

- **If it exists**: Read the file and tell the user:
> "`content.md` already exists for `<pascal>`. Here's what it currently contains:"
>
> (show the content)
>
> "What would you like to update?"

Then help the user edit the existing file. **Do not overwrite it.** Stop following these steps and assist the user conversationally.

- **If it does not exist**: Continue to Step 4.

## Step 4: Ask About Template Structure

Ask the user:

> "Does **<pascal>** have **multiple intents or usages** that need separate content rules?
>
> For example:
> - InfoCard has information / warning / error intents
> - Snackbar has success / loading states
>
> **(A) Yes** — I'll create a theme-based template with sections per intent
> **(B) No** — I'll create a flat template with single Do/Don't sections"

Wait for the user's answer before proceeding.

## Step 5: Create `content.md`

### If the user chose (B) — Flat Template

Create `<folder>/content.md` with:

```markdown
## Content Guidelines

<!-- Voice, tone, and purpose for <pascal> content. -->

## Do

- ...

## Don't

- ...

## Examples

| Context | Good | Bad |
|---------|------|-----|
| ... | ... | ... |
```

### If the user chose (A) — Theme-Based Template

Ask: "What are the intents or usages? (e.g., `information, warning, error` or `success, loading`)"

Then create `<folder>/content.md` with a section per intent. For example, if the user says "information, warning, error":

```markdown
## Content Guidelines

<!-- Voice, tone, and purpose for <pascal> content. -->

## Information

### Do

- ...

### Don't

- ...

## Warning

### Do

- ...

### Don't

- ...

## Error

### Do

- ...

### Don't

- ...

## Examples

| Context | Intent | Good | Bad |
|---------|--------|------|-----|
| ... | ... | ... | ... |
```

Replace the section headings (`## Information`, `## Warning`, `## Error`) with the actual intent names the user provided. Capitalize the first letter of each intent name.

## Step 6: Verify and Report

After creating the file:

1. Confirm the file was created by reading it back
2. Print a summary:

> "Created `<folder>/content.md` for **<pascal>** with a <flat|theme-based> template.
>
> The content tab will appear automatically on the doc page — no other changes needed.
>
> **Next steps:**
> - Edit the file to add your content guidelines
> - Replace the `...` placeholders with real Do/Don't rules and examples
> - Use Claude Code to help you write and structure the guidelines
>
> Run `npm start` to preview the page locally."

## Important Notes

- **Never overwrite** an existing `content.md` — always read and offer to edit
- **No infrastructure changes needed** — the plugin auto-detects `content.md` and the tab renders automatically
- The `## Content Guidelines` heading is intentional — it appears in the tab's table of contents
- Keep the `<!-- comment -->` line as guidance for the content author — they can remove it when done
- The Examples table is mandatory — it's the highest-signal section for AI output quality
  • Step 2: Verify the file was created correctly

Run: cat .claude/commands/add-content-tab.md | head -5

Expected output:

# Add Content Tab

You are adding a content guidelines tab (`content.md`) to an existing Naos Design System component or pattern documentation page.

## Input
  • Step 3: Test the skill by dry-running the logic manually

Verify the skill would work correctly for existing docs:

  1. Check that docs/components/avatar/index.md exists (component folder — should be found)
  2. Check that docs/components/avatar/content.md does NOT exist (should proceed to create)
  3. Check that docs/patterns/empty-states/content.md DOES exist (should show existing content)
  4. Check that docs/components/modal.md exists as single-file (should report error)

Run:

test -f docs/components/avatar/index.md && echo "avatar folder: OK"
test ! -f docs/components/avatar/content.md && echo "avatar no content.md: OK"
test -f docs/patterns/empty-states/content.md && echo "empty-states has content.md: OK"
test -f docs/components/modal.md && test ! -d docs/components/modal && echo "modal is single-file: OK"

Expected: All four lines print "OK".

  • Step 4: Commit
git add .claude/commands/add-content-tab.md
git commit -m "feat: add /add-content-tab slash command for content team

Adds a Claude Code skill that creates content.md files for existing
folder-based component and pattern docs. Supports flat (single Do/Don't)
and theme-based (per-intent sections) templates."

Task 2: Validate end-to-end with a real component​

  • Step 1: Run the command for Avatar

Run /add-content-tab Avatar in Claude Code.

Expected flow:

  1. Finds docs/components/avatar/index.md — identified as component
  2. No content.md exists — proceeds to template question
  3. Choose (B) flat template
  4. Creates docs/components/avatar/content.md
  5. Reports success
  • Step 2: Verify the file was created

Read docs/components/avatar/content.md and confirm it has the flat template structure with ## Content Guidelines, ## Do, ## Don't, ## Examples.

  • Step 3: Verify the tab renders

Run npm start and navigate to the Avatar component page. Confirm the "Content" tab appears and shows the template content.

  • Step 4: Clean up test file

Delete the test content.md — the content team will create the real one:

rm docs/components/avatar/content.md
  • Step 5: Test the "already exists" flow

Run /add-content-tab empty-states in Claude Code.

Expected: The skill finds docs/patterns/empty-states/content.md, reads it, shows the existing content, and asks what the user wants to update. It does NOT overwrite the file.