菜单
Documentation mode selection based on user intent. Use when writing technical documentation or educational content. Covers 4 modes: Tutorial (learning), How-To (tasks), Reference (information), Explanation (understanding).
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | diataxis-framework |
| description | Documentation mode selection based on user intent. Use when writing technical documentation or educational content. Covers 4 modes: Tutorial (learning), How-To (tasks), Reference (information), Explanation (understanding). |
Developer: Daniele Procida Category: Documentation Architecture & User Intent Mapping SIF Layer: Layer 2 (Architecture)
Diátaxis is a systematic approach to technical documentation that maps user needs to four distinct documentation modes. Each mode serves a different user intent and has unique characteristics.
Core Insight: "Documentation serves users with different needs. Match structure to intent."
Action-Oriented
│
Tutorial │ How-To
(Learning) │ (Goals)
│
────────────────────┼────────────────────
│
Explanation │ Reference
(Understanding)│ (Information)
│
Knowledge-Oriented
User Says: "Teach me" You Provide: Hands-on lesson
Characteristics:
Structure:
Example: "Build Your First ML Trading Strategy"
When: Onboarding, education, skill-building
User Says: "Help me solve X" You Provide: Recipe for solution
Characteristics:
Structure:
Example: "How to Optimize Database Queries"
When: Task completion, troubleshooting, specific problems
User Says: "Tell me the facts" You Provide: Technical description
Characteristics:
Structure:
Example: "API Endpoint Reference"
When: Technical specs, API docs, parameters
User Says: "Help me understand" You Provide: Conceptual discussion
Characteristics:
Structure:
Example: "Understanding Time Series Stationarity"
When: Concepts, design decisions, background
| Content Type | Primary Mode | Secondary Mode |
|---|---|---|
| Website Hub | Explanation | How-To |
| Book Chapter | Tutorial | Explanation |
| Blog Post | Explanation | How-To |
| White Paper | Explanation | Reference |
| API Docs | Reference | How-To |
| Getting Started | Tutorial | - |
| Troubleshooting | How-To | Explanation |
| Aspect | Tutorial | How-To | Reference | Explanation |
|---|---|---|---|---|
| Tone | Encouraging | Direct | Neutral | Conversational |
| Focus | Learning | Goal | Information | Understanding |
| Steps | Yes (detailed) | Yes (minimal) | No | No |
| Why | Yes | No | No | Yes (primary) |
| Audience | Beginners | Practitioners | All levels | Interested readers |
Layer 1 (Pyramid): Provides logical structure Layer 2 (Diátaxis): Provides mode-specific template Layer 3 (DITA): Provides reusable snippets per mode Layer 4 (Info Mapping): Provides formatting per mode
Topic: Database Indexing
Tutorial: "Let's add an index to improve query performance. You'll learn how indexes work and build your first index..."
How-To: "To add an index: 1. Identify slow queries 2. Run CREATE INDEX 3. Verify performance..."
Reference: "CREATE INDEX syntax: CREATE INDEX idx_name ON table(column). Parameters: idx_name (string, required)..."
Explanation: "Indexes improve query speed by creating lookup structures. Think of them like a book's index..."
Bad: Tutorial that suddenly becomes reference Good: Pick one mode per section
Bad: Tutorial when user needs quick answer Good: How-To for quick solutions
Bad: Reference mode for website hub Good: Explanation mode for website hub
Match mode to user intent, not your preference
Four modes cover all documentation needs. Don't invent new modes.
Stay consistent within sections. Mode switches confuse readers.
Evidence-first applies to ALL modes. Quantified claims need sources.
This skill should be used when the user asks to "housekeep", "sweep stray transition dirs", "clean up agent-infra debris", "find misplaced .workspace or .claude dirs", or when auditing project trees for the class of debris caused by hooks writing to the wrong project root (nested repos, worker-pool worktrees, stub-only session files, doubled path prefixes). Do NOT use for general project cleanup (see `/system:cleanup`) or for memory garbage collection (see `/memory-gc`).
Write clear, impactful website content for scanners. Use when writing landing pages, service descriptions, CTAs, or above-the-fold content. Covers the 50% test, sentence surgery, power words, page-type guidelines, mobile-first brevity, and techniques for reducing wordiness while maintaining impact.
Match content to what users actually want when they search. Use when creating website pages, blog posts, or any content for search engines. Covers 4 intent types (informational, navigational, transactional, commercial investigation), SERP analysis, query modifiers, and buyer journey mapping.
Technical SEO writing techniques for web content. Use when writing website pages, landing pages, service descriptions, or blog posts for organic search traffic. Covers keyword placement, meta descriptions, heading hierarchy, E-E-A-T principles, internal linking, long-tail keywords, schema markup, and measuring SEO success.
Complete D2 language reference for creating diagrams. Covers shapes, connections, containers, special types (SQL tables, sequences), icons, styling, and advanced features. Use for all D2 diagram generation tasks.
Clarity and simplicity principles for effective diagrams. Focus on essential elements, minimize visual noise, maintain consistency, and use single abstraction levels. Ensures diagrams communicate clearly without clutter.