add-documentation - SKILL.md Agent Skill

name: add-documentation description: Add or update documentation in content/docs/ for features, APIs, or tools

Create well-structured documentation files in `content/docs/` for NowTS features, components, APIs, or tools. **ALWAYS use the provided script** to initialize new docs, then edit the generated file. **MANDATORY: Use the script to create new documentation files:**

.claude/skills/add-documentation/scripts/create-doc.sh <filename> "<title>" "<description>"

# Example
.claude/skills/add-documentation/scripts/create-doc.sh dialog-system "Dialog System" "Global dialog system for modals"

This creates content/docs/<filename>.mdx with proper structure.

Template structure (auto-generated by script):

---
title: "Feature Name"
description: "Brief description of what this feature does"
keywords: ["keyword1", "keyword2", "feature"]
tags: ["developer", "components"]
order: 10
subcategory: "Components"
---

Brief introduction explaining what this feature does and why it's useful.

## Installation

How to set up or enable this feature (if needed).

## Import

\`\`\`tsx
import { Component } from "@/features/feature-name";
\`\`\`

## Usage

### Basic Example

\`\`\`tsx
<Component prop="value" />
\`\`\`

### Advanced Example

\`\`\`tsx
<Component
  prop="value"
  onAction={async () => {
    await doSomething();
  }}
/>
\`\`\`

## API Reference

| Option | Type | Description |
|--------|------|-------------|
| `prop` | `string` | Description of the prop |

## Best Practices

- Tip 1
- Tip 2

Run to verify: pnpm dev and check /docs/[slug]

**CRITICAL: Think before documenting**

Ask yourself these questions:

Who is the audience? (developers, end-users, admins)
What problem does this solve? (document the "why", not just the "how")
What's the minimal example? (start simple, then add complexity)
What are common mistakes? (add warnings/tips)

| Field | Type | Required | Description | |-------|------|----------|-------------| | `title` | `string` | Yes | Display title for the doc | | `description` | `string` | Yes | Brief description (shown in search, SEO) | | `keywords` | `string[]` | Yes | Search keywords | | `tags` | `string[]` | Yes | Categories: `developer`, `guide`, `api`, `components` | | `order` | `number` | Yes | Sort order in navigation (lower = first) | | `subcategory` | `string` | Yes | Grouping: `Guide`, `Components`, `API`, `Tools` | Choose the appropriate subcategory: - **Guide**: Getting started, tutorials, workflows - **Components**: UI components, dialog system, layout - **API**: REST endpoints, server actions, integrations - **Tools**: CLI tools, development utilities 1. **Introduction** - 1-2 sentences explaining what and why 2. **Installation** - Setup steps (if needed) 3. **Import** - Code import statement 4. **Usage** - Basic example first, then advanced 5. **API Reference** - Props/options table 6. **Best Practices** - Tips and common patterns 7. **Troubleshooting** - Common issues (optional) - Always provide working, copy-paste-ready code - Use TypeScript with proper types - Include imports in examples - Show async/await patterns when relevant Documentation without context: ```mdx ## Usage Use `dialogManager.confirm()` to show a dialog. ``` Documentation with context and example: ```mdx ## Usage The Dialog Manager handles confirmation dialogs with automatic loading states.

```tsx dialogManager.confirm({ title: "Delete Item", description: "This cannot be undone.", action: { label: "Delete", onClick: async () => { await deleteItem(); }, }, }); ```

</right>

<wrong>
Overly complex first example:
```mdx
## Basic Usage
\`\`\`tsx
<Component
  prop1="value"
  prop2={42}
  prop3={{ nested: true }}
  onAction={handleAction}
  variant="complex"
/>
\`\`\`

Start with minimal example: ```mdx ## Basic Usage \`\`\`tsx \`\`\`

With Options

```tsx ```

</right>
</anti_patterns>

<existing_docs>
Current documentation files in `content/docs/`:
- `getting-started.mdx` - Project setup guide
- `auth-components.mdx` - Authentication components
- `contact-components.mdx` - Contact form components
- `dialog-manager.mdx` - Dialog system documentation
- `layout-components.mdx` - Layout components
- `markdown-components.mdx` - Markdown rendering
- `safe-actions.mdx` - Server actions patterns
- `zod-route.mdx` - API route validation
- `embedding.mdx` - Testimonial embedding
- `file-adapters.mdx` - File storage adapters
- `api-testimonials-*.mdx` - API documentation
</existing_docs>

<reference_guides>
For detailed documentation patterns and complete examples:

- **`references/documentation-format.md`** - Complete frontmatter reference and structure guidelines
- **`templates/doc-template.mdx`** - Base template used by the script
</reference_guides>

<critical_rules>
**NEVER create documentation files manually. ALWAYS use the script:**

```bash
.claude/skills/add-documentation/scripts/create-doc.sh <filename> "<title>" "<description>"

Then edit the generated file to add content.

- **Script used** to create the file (MANDATORY) - File created in `content/docs/` with `.mdx` extension - All required frontmatter fields present - Clear introduction explaining the "why" - Working code examples with proper imports - API reference table for props/options - Consistent formatting with existing docs