add-documentation

Files (4)

• SKILL.md
• documentation-format.md · references/
• create-doc.sh · scripts/
• doc-template.mdx · templates/

SKILL.md (first lines)

<objective>
Create well-structured documentation files in `content/docs/` for NowStack features, components, APIs, or tools. **ALWAYS use the provided script** to initialize new docs, then edit the generated file.
</objective>

<quick_start>
**MANDATORY: Use the script to create new documentation files:**

```bash
scripts/create-doc.sh <filename> "<title>" "<description>"

# Example
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):

```mdx
---
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]`
</quick_start>

<before_writing>
**CRITICAL: Think before documenting**

Ask yourself these questions:

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

<frontmatter_reference>
| 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` |
</frontmatter_reference>

<subcategories>
Choose the appropriate subcategory:
- **Guide**: Getting started, tutorials, workflows
- **Components**: UI components, dialog system, layout
- **API**: REST endpoints, Convex functions/actions, integrations
- **Tools**: CLI tools, development utilities
</subcategories>

<structure_guidelines>
<section_order>

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)
</section_order>

From zuzu59/z-skills, MIT.

More from zuzu59/z-skills