Skip to main content
skill CX Codex

documentation-standards · terrylica — Claude Code skill: how to install

documentation-standards defines Markdown guidelines tailored for LLM parsing and clean Pandoc PDF export. It stops broken section numbering and unstructured doc sprawl.

MIT 161 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill documentation-standards -a claude-code
Open on GitHub

What documentation-standards does

This skill enforces strict Markdown formatting across project repositories. Its core rule bans manual heading numbers like ## 1. Introduction. Pandoc uses the --number-sections argument during PDF generation. When numbers are typed manually, output files end up with duplicated numbers like 1. 1. Introduction. The skill enforces semantic levels (##, ###) instead.

Structure follows a hub-and-spoke pattern. Core files like CLAUDE.md keep brief summaries, while detailed breakdowns sit inside references/ or skills/ folders. Machine-readable specifications take precedence. OpenAPI 3.1.1 files and JSON Schemas act as canonical truth, while human-readable Markdown links directly to those YAML specs.

The skill relies solely on Read, Glob, and Grep tools to inspect files. It focuses entirely on source formatting before you hand files to an export pipeline.

What it helps with

  • stop duplicate section numbers when generating PDFs with Pandoc
  • organize project files into a hub-and-spoke structure with single sources of truth
  • anchor Markdown guides to canonical OpenAPI 3.1.1 and JSON Schema definitions
  • validate syntax language tags on code blocks and check relative links

Example prompts for the agent

  • Audit docs/guide.md against documentation-standards before building the PDF.
  • Restructure module documentation into a hub-and-spoke layout linked to OpenAPI specs.
  • Strip manual heading numbers from README.md to prepare it for Pandoc.

How to install documentation-standards

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill documentation-standards -a claude-code

2Manually: put the files in place

~/.claude/skills/documentation-standards/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/documentation-standards/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about documentation-standards

How to install documentation-standards in Claude Code?

Run npx skills add terrylica/cc-skills --skill documentation-standards -a claude-code in your terminal. This creates the skill file at ~/.claude/skills/documentation-standards/SKILL.md.

What does documentation-standards do?

It applies structural rules to project documentation. It enforces clean heading levels, keeps specs aligned with machine-readable schemas, and separates summary hubs from reference spokes.

Why does the skill prohibit numbered headings?

Pandoc relies on the --number-sections flag to auto-number PDF chapters. Manual numbers in the Markdown source create duplicated numbers in the rendered output.

Source text

SKILL.md · MIT
---
name: documentation-standards
description: "Apply markdown documentation standards for both LLM consumption and Pandoc PDF export: section numbering, formatting and style. Use when writing or reviewing documentation."
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**:

```markdown
## 1. Introduction

### 1.1 Background

### 1.2 Objectives

## 2. Implementation
```

✅ **Correct**:

```markdown
## 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

- [ ] Follows hub-and-spoke pattern (essentials in main doc, details in references)
- [ ] Links to deeper documentation for progressive disclosure
- [ ] Single source of truth (no duplicate content across docs)

### Markdown Formatting

- [ ] No manual section numbering in headings
- [ ] Semantic heading levels (##, ###, ####) used correctly
- [ ] Code blocks have language identifiers for syntax highlighting
- [ ] Links use markdown format `[text](url)`, not bare URLs

### Machine-Readable Content

- [ ] Workflows documented as OpenAPI 3.1.1 specs (when applicable)
- [ ] Data structures use JSON Schema (when applicable)
- [ ] Configuration uses YAML with validation (when applicable)
- [ ] Human docs reference canonical machine-readable specs

### File Organization

- [ ] Documentation lives in appropriate location:
  - Global standards → docs/standards/
  - Skill documentation → skills/{skill-name}/references/
  - Project documentation → {project}/.claude/ or {project}/docs/
- [ ] Index files provide navigation (INDEX.md, README.md)

## Related Resources

- **ASCII Diagram Validation**: [ascii-diagram-validator](../ascii-diagram-validator/SKILL.md) - Validate ASCII diagrams in markdown
- **Skill Architecture**: See skill-architecture plugin for creating effective skills

## Examples

### Good Hub-and-Spoke Structure

**Hub (CLAUDE.md)**:

```markdown
## 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):

```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
      # ... detailed spec
```

**Human Documentation** (README.md):

```markdown
## 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:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **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.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Writing and docs →

documentation-standards by other authors comes first.

documentation-standards pr-pm documentation-standards defines repository documentation layout: keeps internal contributor docs in development/docs/, public manuals in docs/, and root files like README.md. CX Codex +1 1installs documentation-tools Legion Code Inc. documentation-tools is a Claude Code plugin that generates, verifies, and packages software documentation and API guides from source code into PDF, Word, and Markdown. CX Codex ★ 96repo stars Technical Documentation taste f Technical Documentation taste — a prompt defining standards for technical documentation for developers. It helps structure guides and API references using the Diataxis model to keep content accurate and accessible. GP ChatGPT ★ 178,201repo stars academic-writing-standards seabbs The academic-writing-standards Claude Code skill guides scientific manuscript editing, including Pandoc citation checks and bibliography cross-referencing. CX Codex +1 130installs translate-book deusyu translate-book translates books from PDF, DOCX, EPUB, or Markdown with parallel sub-agents and exports the result as HTML, DOCX, EPUB, or PDF. CX Codex +1 2,100installs whitepaper adobe A skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that converts a Markdown file into a typeset PDF whitepaper. It runs end-to-end and removes intermediate files right after the PDF is built. CX Codex +1 1,600installs doc-to-markdown daymade doc-to-markdown is a Claude Code skill that converts DOCX, PDF, PPTX, and saved HTML to Markdown with automated cleanup. It activates on prompts to convert or parse documents. CX Codex +1 945installs

From the same set79

The whole set →
ascii-diagram-validator The ascii-diagram-validator skill finds structural alignment problems in Markdown box diagrams and reports where they occur. Run it after editing architecture docs or README files. CX Codex +1 217installs calendar-event-manager calendar-event-manager builds macOS Calendar events with layered sound alarms and matching Reminders, so a meeting does not slip past you. CX Codex +1 214installs agent-reach The agent-reach skill equips your agent with web search and reading capabilities across 17 platforms: social networks (Twitter, Reddit, Weibo, Xiaohongshu, Douyin, Bilibili, V2EX), job boards (LinkedIn), GitHub, YouTube, podcasts. CX Codex +1 195installs code-hardcode-audit code-hardcode-audit scans codebases for raw credentials, magic numbers, and duplicated blocks. It coordinates nine static analysis utilities through uv. CX Codex +1 166installs imessage-query imessage-query pulls conversations out of ~/Library/Messages/chat.db with SQLite, searches across chats, and recovers text from binary attributedBody blobs. CX Codex +1 159installs clickhouse-architect clickhouse-architect designs ClickHouse v24.4+ table schemas, selects compression codecs, and configures sorting keys for cloud and self-hosted clusters. CX Codex +1 157installs dead-code-detector dead-code-detector finds unreachable code, unused imports, and dead exports across Python, TypeScript, and Rust codebases. Useful before major releases and refactoring sprints. CX Codex +1 150installs plotext-financial-chart plotext-financial-chart builds pure text financial line charts for Markdown files using plotext. It helps display price paths directly in GitHub documentation without external images. CX Codex +1 146installs

Project sponsors

Companies that keep this analytics open