Documentation Creator Skill

Creates documentation by understanding context first, then writing in the correct voice for the target audience.

Trigger

• /docs <topic> [--site engineering|product|public|support]
• "Document the X feature"
• "Add docs for Y API"
• "Create documentation about Z"

Execution Flow

1. Capture Intent

Extract from user input:

• Topic — what to document
• Site hint — explicit --site flag or inferred from context

2. Investigate Existing Docs

Search docs/ repository for:

• Duplicates — same/similar topic already documented
• Related docs — should be referenced or extended
• Gaps — what's missing in current coverage
• Location patterns — where similar content lives

Search across engineering/, product/, public/, support/.

3. Clarify with User

Use AskUserQuestion to gather what's not yet clear:

• Audience → determines site (if not specified via --site)
• Doc type → Reference, Guide, Overview, Troubleshooting
• Relationship to existing docs found in step 2
• Domain/Project if not obvious from context

Questions should be informed by step 2 findings.

4. Read the Site's CLAUDE.md

This step is mandatory. Before writing anything, read the target site's writing rules:

Site	CLAUDE.md Path
Engineering	docs/engineering/CLAUDE.md
Product	docs/product/CLAUDE.md
Public	docs/public/CLAUDE.md
Support	(no CLAUDE.md — use plain, helpful language for end users)

Each CLAUDE.md defines audience, voice, structure, terminology, and examples specific to that site. Follow them exactly.

Quick Voice Reference

Site	Person	Voice	Focus
Engineering	3rd person	Technical, precise	How it works, architecture, debugging
Product	1st plural ("we", "our system")	Business-aware, clear	User value, features, workflows
Public	2nd person ("you", "your")	Developer-friendly, step-by-step	Integration, API usage, examples
Support	2nd person ("you")	Simple, helpful	How-to for end users

5. Determine Location

Use docs-nav skill reference for:

• Site selection by audience
• Domain folder mapping
• Directory structure

Content Type	Site	Path
API internals, architecture	Engineering	engineering/docs/
Project-specific tech docs	Engineering	engineering/projects/{Project}/
Database queries	Engineering	engineering/docs/Query Library/
Feature specs, user flows	Product	product/docs/
Customer use cases	Product	product/docs/Tenants/
Public API endpoints	Public	public/docs/Rest_API/
Integration guides	Public	public/docs/Integrations/
Customer help	Support	support/docs/

6. Create Document

Generate file with:

• Frontmatter — id, slug, title, sidebar_label, sidebar_position, author, tags
• Structure matching doc type (see below)
• Links to related docs found in step 2
• Tags — minimum 3 from site's docs/tags.yml
• Writing style — per site's CLAUDE.md rules read in step 4

Frontmatter Template

---
id: filename_in_snake_case
slug: filename_in_snake_case
title: Document Title
sidebar_label: Docs Creator
sidebar_position: 1
author: Team Name
tags: [category, subcategory, type]
---

Doc Type Structures

Type	Structure
Reference	Overview → Sections → Related docs
Guide	Prerequisites → Steps → Next steps
Overview	Introduction → How it works → Key concepts
Troubleshooting	Problem → Cause → Solution

Link Format

• Same docs plugin: [text](./folder/file.md)
• Cross-plugin: [text](../projects/farfalla/overview) (no .md)

7. Validate & Report

cd docs && npm run validate

Report:

## Documentation Created

**File:** {path/to/doc.md}
**Site:** {site}
**Type:** {doc_type}

### Related Docs Found
- {existing related docs}

### Next Steps
1. Review and edit content
2. Preview: `npm run start:{site}`
3. Commit when ready