К основному содержанию
скилл CX Codex

documentation-standards · terrylica — скилл для Claude Code: установка

Скилл documentation-standards задаёт правила оформления Markdown для чтения моделями и экспорта в PDF через Pandoc. Спасает от поломанной нумерации глав и хаоса в структуре.

MIT 161 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill documentation-standards -a claude-code
Открыть на GitHub

Что делает documentation-standards

Скилл внедряет строгие правила разметки документации в репозитории. Главный запрет касается ручной нумерации заголовков вроде ## 1. Введение. Pandoc при вызове с флагом --number-sections нумерует разделы сам. Если проставить цифры руками, в итоговом документе получится 1. 1. Введение. Скилл требует опираться только на уровни заголовков ## и ###.

Архитектура опирается на принцип hub-and-spoke. Центральный документ CLAUDE.md содержит базовые ориентиры, а подробности выносятся в отдельные файлы каталогов references/ или skills/. При этом машиночитаемые спецификации OpenAPI 3.1.1 и схемы JSON Schema имеют приоритет перед текстовыми описаниями: человек читает Markdown, который ссылается на канонический контракт в YAML.

Для проверки разметки агенту разрешены только три инструмента: Read, Glob и Grep. Без установленного Pandoc в системе скомпилировать сам PDF не выйдет, но скилл отвечает именно за чистоту разметки исходников перед сборкой.

Какие задачи решает

  • исключить дублирование номеров разделов при компиляции PDF через Pandoc
  • разделить документацию на центральный хаб и детальные справочники
  • привязать пояснительный Markdown к спецификациям OpenAPI 3.1.1 и JSON Schema
  • проверить разметку на наличие языковых тегов у блоков кода и формат ссылок

Примеры запросов агенту

  • Проверь docs/guide.md по правилам documentation-standards перед экспортом в PDF.
  • Оформи документацию нового модуля по схеме hub-and-spoke с ссылками на спецификацию OpenAPI.
  • Убери ручную нумерацию глав в README.md, чтобы подготовить файл к сборке через Pandoc.

Как установить documentation-standards

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/documentation-standards/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о documentation-standards

Как установить documentation-standards в Claude Code?

Выполните в терминале команду npx skills add terrylica/cc-skills --skill documentation-standards -a claude-code. Скилл запишется в каталог ~/.claude/skills/documentation-standards/SKILL.md.

Что делает documentation-standards?

Он задаёт шаблоны структуры и стиля документации. Инструмент следит за семантикой заголовков, связкой с машинными схемами и разделением файлов на вводные хабы и детальные справочники.

Почему скилл запрещает нумеровать заголовки вручную?

При генерации PDF через Pandoc используется флаг --number-sections. Если в исходном Markdown уже стоят цифры, утилита добавит второй номер поверх ручного.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тексты и документация» →

Сначала — documentation-standards от других авторов.

documentation-standards pr-pm Скилл documentation-standards задаёт правила структуры документации: разделяет внутренние инструкции для контрибьюторов, пользовательские руководства в docs/ и скиллы в .claude/skills/. CX Codex +1 1установок documentation-tools Legion Code Inc. Плагин documentation-tools автоматизирует аудит кодовой базы, сборку документации API и выгрузку отчётов в PDF, Word и Markdown. CX Codex ★ 96звёзд репо Technical Documentation taste f Промпт Technical Documentation taste для ChatGPT, Claude.ai и Claude Code задаёт стандарты технической документации. Помогает структурировать руководства и описание API по модели Diataxis для их актуальности и доступности. GP ChatGPT ★ 178 201звёзд репо academic-writing-standards seabbs Скилл academic-writing-standards для Claude Code задаёт правила рецензирования и правки научных статей, проверки цитат Pandoc и файлов .bib. CX Codex +1 130установок translate-book deusyu Скилл translate-book переводит книги из PDF, DOCX, EPUB или Markdown через параллельные субагенты и собирает результат в HTML, DOCX, EPUB или PDF. CX Codex +1 2 100установок whitepaper adobe Скилл whitepaper для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI конвертирует Markdown-файл в типографски оформленный PDF-вайтпейпер. Запускается одной командой и удаляет исходные файлы сразу после сборки. CX Codex +1 1 600установок doc-to-markdown daymade Скилл doc-to-markdown для Claude Code и Codex конвертирует DOCX, PDF, PPTX и сохранённый HTML в Markdown с автоматической зачисткой разметки. Включается при запросах на парсинг документов. CX Codex +1 945установок

Из того же набора79

Весь набор →
ascii-diagram-validator Скилл ascii-diagram-validator находит структурные ошибки в схемах с рамками и соединителями в Markdown. Запустите его после правок документации, чтобы проверить выравнивание. CX Codex +1 217установок calendar-event-manager Скилл calendar-event-manager заводит события в macOS Calendar со звуковыми будильниками и парными напоминаниями в Reminders, чтобы встреча не прошла мимо. CX Codex +1 214установок agent-reach Скилл agent-reach даёт агенту возможность искать и читать информацию с интернета: социальные сети (Twitter, Reddit, Weibo, Xiaohongshu, Douyin, Bilibili, V2EX), карьерные сайты (LinkedIn), GitHub, YouTube, подкасты, статьи и RSS-ленты. CX Codex +1 195установок code-hardcode-audit Скилл code-hardcode-audit находит захардкоженные пароли, токены API, магические числа и дубликаты кода. Запускает оркестрацию девяти статических анализаторов через uv. CX Codex +1 166установок imessage-query Скилл imessage-query читает ~/Library/Messages/chat.db через SQLite: достаёт переписку с контактом, ищет по ключевым словам и вытаскивает текст из бинарного attributedBody. CX Codex +1 159установок clickhouse-architect Скилл clickhouse-architect проектирует схемы ClickHouse v24.4+, подбирает кодеки сжатия и настраивает ключи сортировки под облачные и серверные развёртывания. CX Codex +1 157установок dead-code-detector Скилл dead-code-detector ищет неиспользуемые функции, импорты и файлы в проектах на Python, TypeScript и Rust. Помогает подготовить кодовую базу к релизу и почистить зависимости. CX Codex +1 150установок plotext-financial-chart Скилл plotext-financial-chart строит текстовые финансовые графики в ASCII для Markdown-файлов через plotext. Помогает наглядно показать ценовые уровни прямо в документации на GitHub. CX Codex +1 146установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой