Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

documentation-standards

/documentation-standards

Stosuje standardy dokumentacji markdown dla odbioru przez LLM i eksportu PDF przez Pandoc: numeracja sekcji, formatowanie i styl.

Repozytorium
cc-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Stosuje standardy dokumentacji markdown dla odbioru przez LLM i eksportu PDF przez Pandoc: numeracja sekcji, formatowanie i styl.

Oryginalny opis (EN)

Apply markdown documentation standards for both LLM consumption and Pandoc PDF export: section numbering, formatting and style. Use when writing or reviewing documentation.

Jak działa

  1. Overview
  2. When to Use This Skill
  3. Core Principles
  4. Standards Checklist
  5. Related Resources
  6. Examples
  7. Summary
  8. Troubleshooting
  9. Post-Execution Reflection
Sekcje z nagłówków SKILL.md, w oryginale · 214 linii, 944 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (2)
  • SKILL.md 7 KB
  • references/evolution-log.md 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · terrylica/cc-skills100MIT
hculap/better-code100MIT
jagreehal/jagreehal-claude-skills100MIT
zircote-plugins/documentation-review100MIT
madappgang/magus91MIT

Migawka bazy z 13.11.2026 · wersja paczki 846f3af9ca99 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100documentation-quality
    Ustala standardy jakości dokumentacji i zasady pisania: reguły formatowania, metryki jakości, wytyczne pisania i spójny styl dokumentacji w projekcie.
  • 100pdf-generation
    Składa rozdziały w markdownie w książkę lub dokumentację w PDF, przy użyciu pandoc i weasyprint.
  • 86md-to-pdf-closed-source
    Buduje PDF z Markdowna za pomocą pandoc, zamieniając tekst na plik gotowy do wysyłki.
  • 100python-code-style
    Ustala styl kodu Python: linting, formatowanie, nazewnictwo i docstringi, przy pisaniu nowego kodu, przeglądzie stylu i konfiguracji linterów.
  • 100documentation
    Stosuje standardy dokumentacji przy zmianach kodu: pisze i przegląda dokumentację, docstringi i komentarze, opisuje publiczne API i zmiany widoczne dla użytkownika oraz poprawia README.
  • 86markdown
    Pilnuje standardów dokumentacji i treści przy edycji plików Markdown .md.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.