Add documentation-docusaurus agent skill

Packages generic-documentation-v1 as documentation-docusaurus: Diataxis quadrants, structure and voice rules, and four references for patterns, writing, config, and deployment. Content preserved from the source; renames the skill, strengthens the description for triggering, and converts the reference list into a routing table stating when to load each file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-30 22:58:08 +03:00
parent ed7c7f0d95
commit a596731f67
6 changed files with 1189 additions and 1 deletions
@@ -0,0 +1,185 @@
+---
+name: documentation-docusaurus
+description: >
+  Opinionated guidance for building and restructuring Docusaurus documentation sites on the
+  Diátaxis framework — separating tutorials, how-to guides, reference, and explanation, and
+  refusing to mix them on one page. Use when creating a new docs site or page, reorganising an
+  existing one, deciding which quadrant a page belongs to, writing frontmatter, sidebars, or
+  admonitions, editing docusaurus.config.ts, applying voice and inclusive-language standards,
+  or setting up deployment to Vercel, Netlify, GitHub Pages, or Cloudflare Pages. Triggers on
+  docs/, blog/, docusaurus.config, sidebars.ts, .mdx files, or any request to write, improve,
+  or restructure documentation — even when the user only says "write docs", "document this",
+  or "the docs are a mess". Asks who the reader is and what they should be able to DO before
+  writing, because the answer decides the structure.
+license: MIT
+metadata:
+  author: workspace-skills-code-agent
+  version: "1.0"
+  spec: agentskills.io/specification
+  framework: Diátaxis
+compatibility: Designed for Docusaurus v3. Works with Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments
+---
+
+# Docusaurus Documentation Skill
+
+*Opinionated guidance for building documentation people actually read.*
+
+## My Philosophy
+
+Documentation isn't about documenting—it's about **enabling**. Every page should answer one question: "What can the reader DO after reading this?"
+
+I follow the **Diátaxis framework**. Before writing anything, identify which quadrant you're in:
+
+| Type | Purpose | User State | Question Answered |
+|------|---------|------------|-------------------|
+| **Tutorial** | Learning | "I'm new, teach me" | "Can you teach me to...?" |
+| **How-to** | Doing | "I need to accomplish X" | "How do I...?" |
+| **Reference** | Information | "I need to look up Y" | "What is the API for...?" |
+| **Explanation** | Understanding | "I want to understand why" | "Why does...?" |
+
+**Don't mix them.** A tutorial that becomes reference midway loses both audiences.
+
+## Before You Write: Questions I'll Ask
+
+When you ask me to create documentation, I need to understand:
+
+1. **Who is reading this?** (New user? Developer? API consumer? Decision maker?)
+2. **What should they be able to DO after?** (Not "know"—DO)
+3. **Which Diátaxis quadrant?** (Tutorial/How-to/Reference/Explanation)
+4. **What do they already know?** (Prerequisites matter)
+
+If you haven't thought through these, I'll ask. Good docs require clear thinking first.
+
+## Structure: My Strong Opinions
+
+### Sidebar Organization
+
+```
+docs/
+├── getting-started/          # Tutorials: learning journeys
+│   ├── _category_.json       # collapsed: false
+│   └── ...
+├── guides/                   # How-tos: task completion
+├── concepts/                 # Explanation: understanding
+├── reference/                # Reference: lookup
+│   ├── api/
+│   └── configuration/
+└── resources/                # Links, community, changelog
+```
+
+**Why this order?** It matches the reader's journey: Learn → Do → Understand → Look up.
+
+### Frontmatter: Non-Negotiables
+
+Every doc needs these. No exceptions:
+```yaml
+---
+title: "Action-Oriented Title"        # What they'll DO, not what it IS
+description: "One sentence outcome"   # Appears in search, make it count
+---
+```
+
+Skip `sidebar_position` unless order matters semantically. Let alphabetical work.
+
+### Writing Rules I Enforce
+
+**Tutorials:**
+- Start with what they'll BUILD, not what they'll LEARN
+- One path only—no "alternatively" or "you could also"
+- Every step produces visible output
+- Link to explanation, don't embed it
+
+**How-to Guides:**
+- Title format: "How to [verb] [thing]"
+- Assume competence—skip basics
+- Start with the goal, not the tool
+- Include "What you'll need" upfront
+
+**Reference:**
+- Mirror the code structure exactly
+- Tables over prose for specs
+- Examples for every endpoint/function
+- No tutorials hiding in reference
+
+**Explanation:**
+- Answer "why" not "how"
+- Connect to bigger picture
+- Acknowledge trade-offs and alternatives
+- Can be opinionated—this is where you explain decisions
+
+## Inclusive Language: Required
+
+Use these replacements. This isn't optional:
+
+| Avoid | Use Instead |
+|-------|-------------|
+| whitelist/blacklist | allowlist/blocklist |
+| master/slave | primary/replica, main/secondary |
+| sanity check | confidence check, validation |
+| dummy value | placeholder, sample |
+| guys | folks, everyone, team |
+| simple/easy | (just remove it) |
+
+**Why "simple" is banned:** What's simple to you isn't simple to the reader. Saying "simply run X" makes struggling readers feel dumb.
+
+**Pronouns:** Use "you" for the reader. Use "they" for hypothetical users. Avoid "we" unless it's genuinely collaborative.
+
+## Dynamic Documentation Patterns
+
+### Interactive Elements (Use Sparingly)
+
+Tabs for platform differences:
+```mdx
+<Tabs groupId="os">
+  <TabItem value="mac" label="macOS" default>
+```
+
+Details for optional deep-dives:
+```mdx
+<details>
+<summary>Why does this matter?</summary>
+...explanation that most readers can skip...
+</details>
+```
+
+**Don't use tabs for:** Code language alternatives (pick one and show it well), or "beginner vs advanced" (separate pages instead).
+
+### Admonitions: The Hierarchy
+
+```
+:::tip        → "This will make your life easier"
+:::note       → "Relevant context you might miss"
+:::warning   → "This could cause problems"
+:::danger    → "This WILL break things if ignored"
+```
+
+**One admonition per section max.** If everything is highlighted, nothing is.
+
+## What I Won't Do
+
+- Create docs without understanding the audience
+- Mix documentation types in one page
+- Add "simple" or "easy" to instructions
+- Generate walls of code without context
+- Skip frontmatter description fields
+- Create sidebars deeper than 3 levels
+
+## Reference Files
+
+Load the one that matches the task. Don't read all four.
+
+| You're about to | Read |
+|---|---|
+| Write a page, or decide which quadrant it belongs in | [references/diataxis-patterns.md](references/diataxis-patterns.md) — copy-ready template per quadrant, the decision tree, and how to link between them |
+| Write or edit prose, headings, lists, or code examples | [references/writing-guide.md](references/writing-guide.md) — voice, words to cut, inclusive language, pre-publish checklist |
+| Touch `docusaurus.config.ts` | [references/config-reference.md](references/config-reference.md) — the options that matter, sensible defaults, config anti-patterns |
+| Ship the site, or debug a failing build | [references/deployment.md](references/deployment.md) — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |
+
+## Getting Started
+
+Tell me:
+1. What documentation you're building
+2. Who it's for
+3. What they should be able to do after
+
+I'll ask follow-up questions, then we'll build something people actually want to read.