| name | documentation-standards |
| description | Apply markdown documentation standards optimized for both LLM consumption and Pandoc PDF generation. Use whenever the user is writing or. |
| allowed-tools | Read, Glob, Grep |
Documentation Standards
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Overview
Standards for writing markdown documentation optimized for both LLM consumption and conversion to professional PDFs using Pandoc. Ensures consistency across all documentation.
When to Use This Skill
Use when:
- Writing markdown documentation (README, skills, guides, specifications)
- Creating new skills that include markdown content
- Authoring content that may be converted to PDF
- Reviewing documentation for standards compliance
Core Principles
1. LLM-Optimized Documentation Architecture
Machine-Readable Priority: OpenAPI 3.1.0 specs, JSON Schema, YAML specifications take precedence over human documentation.
Why: Structured formats provide unambiguous contracts that both humans and LLMs can consume reliably. Human docs supplement, don't replace, machine-readable specs.
Application:
- Workflow specifications → OpenAPI 3.1.1 YAML in specifications/
- Data schemas → JSON Schema with examples
- Configuration → YAML with validation schemas
- Human docs → Markdown referencing canonical machine-readable specs
2. Hub-and-Spoke Progressive Disclosure
Pattern: Central hubs (like CLAUDE.md, INDEX.md) link to detailed spokes (skills, docs directories).
Structure:
CLAUDE.md (Hub - Essentials Only)
↓ links to
Skills (Spokes - Progressive Disclosure)
├── SKILL.md (Overview + Quick Start)
└── references/ (Detailed Documentation)
Rules:
- Hubs contain essentials only (what + where to find more)
- Spokes contain progressive detail (load as needed)
- Single source of truth per topic (no duplication)
3. Markdown Section Numbering
Critical Rule: Never manually number markdown headings.
❌ Wrong:
## 1. Introduction
### 1.1 Background
### 1.2 Objectives
## 2. Implementation
✅ Correct:
## Introduction
### Background
### Objectives
## Implementation
Rationale:
- Pandoc's
--number-sections flag auto-numbers all sections when generating PDFs
- Manual numbering creates duplication: "1. 1. Introduction" in rendered output
- Auto-numbering is consistent, updates automatically when sections reorganize
- Applies to ALL markdown: documentation, skills, project files, README files
Rule: If markdown might ever convert to PDF, never manually number headings. Use semantic heading levels (##, ###) and let tools handle numbering.
Standards Checklist
Use this checklist when creating or reviewing documentation:
Structure
Markdown Formatting
Machine-Readable Content
File Organization
Related Resources
- ASCII Diagram Validation: ascii-diagram-validator - Validate ASCII diagrams in markdown
- Skill Architecture: See skill-architecture plugin for creating effective skills
Examples
Good Hub-and-Spoke Structure
Hub (CLAUDE.md):
## PDF Generation from Markdown
**Quick Start**: Use pandoc-pdf-generation skill
**Critical Rules**:
1. Never write ad-hoc pandoc commands
2. Always verify PDFs before presenting
3. See skill for detailed principles
Spoke (skill/SKILL.md):
- Quick start with examples
- Link to references/ for detailed documentation
- Progressive disclosure as needed
Good Machine-Readable Documentation
Workflow Specification (specifications/hook-prompt-capture.yaml):
openapi: 3.1.1
info:
title: Hook Prompt Capture Workflow
version: 1.0.0
paths:
/capture-prompt:
post:
summary: Capture user prompt from hook
Human Documentation (README.md):
## Workflow
See [hook-prompt-capture.yaml](./specifications/hook-prompt-capture.yaml)
for complete workflow specification.
Quick overview: ...
Summary
Documentation standards ensure:
- Consistency across all workspace documentation
- LLM optimization through machine-readable formats
- Maintainability via hub-and-spoke + single source of truth
- PDF compatibility through proper markdown formatting
Follow these standards for all documentation.
Troubleshooting
| Issue | Cause | Solution |
|---|
| Double section numbers in PDF | Manual numbering in markdown | Remove manual numbers, use --number-sections only |
| Broken links in PDF | Relative paths incorrect | Use repo-root paths for cross-document links |
| Code block no syntax color | Missing language identifier | Add language after opening triple backticks |
| Tables render poorly | Column widths too wide | Use shorter headers or pipe-table format |
| Hub doc too long | Too much detail in hub | Move details to spoke documents, link from hub |
| Duplicate content | Same info in multiple docs | Identify SSoT, remove duplicates, add links |
| YAML spec not rendering | Wrong file extension | Use .yaml extension for OpenAPI specs |
| Index navigation missing | No INDEX.md or README.md | Create navigation index in each directory |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
