# Skill Doc > Generate or update comprehensive documentation (.md and .html) for any skill. Use when the user asks to document a skill, create a guide for a skill, generate skill docs, update skill docs, or write documentation for a slash command. Triggers on requests like "documenta a skill X", "cria doc para a skill", "gera guia da skill", "cria documentação da skill", "atualiza a doc da skill X", "skill-doc /open-pr". - Skill: `thgmatajs/skill-doc` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add thgmatajs/skill-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/thgmatajs/skill-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: thgMatajs (https://skillmd.com/u/thgmatajs) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/thgmatajs/skill-doc --- # Skill Doc — Documentation Generator for Skills Generates or updates comprehensive documentation (.md and .html) for any skill, using a **section-based architecture** for efficient incremental updates. **Path convention:** `$SKILL_DIR` is the directory containing this `SKILL.md` (wherever `skill-doc` is installed — project `.claude/skills/skill-doc/` or global `~/.claude/skills/skill-doc/`). Run the builder as `$SKILL_DIR/build.sh `. **IMPORTANT**: The generated documentation output (.md and .html files) MUST be written in **Brazilian Portuguese** with correct accents. This SKILL.md (the instructions) is in English, but all generated content is in pt-BR. ## Input `$ARGUMENTS` = `[skill-name]` - skill-name: name of the skill to document (e.g., `open-pr`, `investigate`, `commit`) - If omitted, use `AskUserQuestion` to ask which skill to document --- ## Architecture Overview ### Section-Based HTML Instead of a single monolithic HTML file, docs are built from **individual section files** that are concatenated by `build.sh`. This enables: - **Incremental updates**: change one section without regenerating the entire HTML - **Shared CSS/JS**: all skills share `theme/skill-doc.css` and `theme/skill-doc-mermaid.js` - **Lower token cost**: updating a 30-line section vs rewriting a 340-line file ### File Structure ``` .claude/skills/skill-doc/ ├── SKILL.md # This file (instructions) ├── theme/ │ ├── skill-doc.css # Shared CSS (all skills reference this) │ └── skill-doc-mermaid.js # Mermaid.js initialization config ├── build.sh # Concatenates sections → final HTML └── templates/ └── html-template.html # DEPRECATED — kept as visual reference only .claude/skills/{name}/docs/ ├── {name}-skill-guide.md # Markdown documentation (single file) ├── {name}-skill-guide.html # Final assembled HTML (built from sections) └── sections/ # Individual HTML section files ├── 00-head.html # + + opening + h1 + subtitle ├── 01-toc.html # Table of contents with anchor links ├── 02-overview.html # Overview + feature cards + invocation examples ├── 03-flow.html # Mermaid.js flow diagram ├── 10-{custom}.html # Skill-specific sections (10–89 range) ├── ... ├── 90-scenarios.html # Scenarios and examples ├── 92-tools.html # Tools, files, skill structure ├── 94-steps.html # Steps summary table ├── 96-rules.html # Critical rules list └── 99-footer.html # ``` ### Section Numbering Convention | Range | Purpose | Fixed? | |-------|---------|--------| | `00` | Head (DOCTYPE, CSS link, title) | Yes | | `01` | Table of contents | Yes | | `02` | Overview + cards | Yes | | `03` | Flow diagram (Mermaid) | Yes | | `10`–`89` | Skill-specific sections | No — adapt to skill | | `90` | Scenarios and examples | Yes | | `92` | Tools and files | Yes | | `94` | Steps summary table | Yes | | `96` | Critical rules | Yes | | `99` | Footer (closing tags) | Yes | --- ## Step 1: Locate the Skill 1. Search for the skill in these locations (in order): - `.claude/skills/{skill-name}/SKILL.md` (project) - `.agents/skills/{skill-name}/SKILL.md` (project agents dir) - `~/.claude/skills/{skill-name}/SKILL.md` (global) - `~/.agents/skills/{skill-name}/SKILL.md` (global agents dir) - `~/.claude/commands/{skill-name}.md` (legacy global command) 2. If not found, ask the user for the correct path or name. 3. Read the full `SKILL.md` of the found skill. 4. If a `references/` folder exists, read all reference files for additional context. --- ## Step 2: Detect Mode Check if documentation already exists: ``` Glob: .claude/skills/{skill-name}/docs/sections/*.html Glob: .claude/skills/{skill-name}/docs/{skill-name}-skill-guide.md ``` ### Mode Decision | Existing sections/ | Existing .md | Existing .html (no sections) | Mode | |---|---|---|---| | No | No | No | **create** — generate everything from scratch | | No | No | Yes (legacy) | **migrate** — read legacy HTML, generate sections from it | | Yes | Yes | Yes | **update** — compare SKILL.md vs existing, update changed sections | | No | Yes | No | **create** — sections missing, regenerate HTML sections from .md | Announce the detected mode to the user before proceeding. --- ## Step 3: Analyze the Skill Extract from the `SKILL.md`: 1. **Metadata**: name, description, arguments, allowed tools 2. **Steps/Phases**: list each step with name, description, and whether it is conditional 3. **Rules**: all critical rules and restrictions 4. **Tools**: which MCPs, CLIs, scripts, and tools are used 5. **Files**: which project files the skill reads or modifies 6. **Conditional decisions**: where the skill asks the user or makes context-based decisions 7. **Scenarios**: identify the main usage scenarios (minimum 3, ideal 5) --- ## Step 4: Generate Markdown Documentation Create or update `{skill-name}-skill-guide.md` as a **single file** following this structure: ### Markdown Structure ```markdown # Skill {Name} — Guia Completo Documentação da skill de {short description}. --- ## Visão Geral {What the skill does, when to use it, and main features} ### Funcionalidades {Table with main features} ### Formas de Invocação {Examples of how to call the skill with different arguments} --- ## Fluxo Completo — Diagrama {ASCII diagram showing the skill's step flow} --- ## {Skill-specific sections} {One section per important concept} {Each section must have: text explanation + table or diagram} --- ## Cenários e Exemplos {Minimum 3 scenarios covering: happy path, user prompt case, edge case} --- ## Regras Críticas {Numbered list with ALL skill rules} --- ## Arquivos da Skill {Directory tree of the skill} ### Arquivos Relacionados {Table: file -> purpose} ### Ferramentas Utilizadas {Table: tool -> purpose -> where used} --- ## Tabela Resumo de Steps {Table: step, name, description, conditional?} ``` ### Markdown Rules 1. **ALWAYS write in Brazilian Portuguese with correct accents** (é, ã, ç, ú, etc.) 2. Use tables for structured data 3. Use ASCII diagrams for flows (inside ``` blocks) 4. Use inline `code` for file names, commands, variables 5. Use **bold** for emphasis on rules and important terms 6. Minimum 3 example scenarios, ideal 5 7. Every section must have at least one supporting table or diagram --- ## Step 5: Generate HTML Sections Generate individual HTML section files inside `docs/sections/`. ### Mode: create Generate ALL sections from scratch. ### Mode: update 1. Read each existing section file 2. Compare content against the current SKILL.md analysis (Step 3) 3. Identify which sections are **stale** (content no longer matches SKILL.md) 4. Regenerate ONLY the stale sections using `Write` (for new) or `Edit` (for partial changes) 5. If sections were added or removed → always regenerate `01-toc.html` 6. Report to the user which sections were updated and which were kept ### Mode: migrate 1. Read the legacy monolithic HTML file 2. Extract the content sections from it 3. Generate all section files from the extracted content 4. The legacy HTML is overwritten by `build.sh` output ### Section Templates #### 00-head.html ```html Skill {SKILL_TITLE} — Guia Completo

/{SKILL_NAME} — Guia Completo

{SUBTITLE}

``` #### 01-toc.html ```html ``` #### 02-overview.html ```html

1. Visão Geral

{Description}

🔍 {Feature}

{Description}

Formas de Invocação

/{SKILL_NAME} arg1    # Description
``` #### 03-flow.html ```html

2. Fluxo Completo

flowchart TD A["/{SKILL_NAME} input"] --> B{Decision} B -->|Option A| C["Step 1"] B -->|Option B| D["Step 2"] C --> E["Output"] D --> E style A fill:#1f6feb,stroke:#58a6ff,color:#fff style E fill:#8b5cf6,stroke:#bc8cff,color:#fff
``` #### 10-{custom}.html through 89-{custom}.html (skill-specific) ```html

{N}. {Section Title}

{Explanation}

Column 1Column 2Status
ValueValueSIM
``` #### 90-scenarios.html ```html

{N}. Cenários e Exemplos

Cenário 1 — {Short description}
Entrada: /{SKILL_NAME} args
Contexto: {context}
Resultado: {result}
``` #### 92-tools.html ```html

{N}. Ferramentas e Arquivos

Ferramentas Utilizadas

FerramentaFunçãoUsada em
{tool}{function}{steps}

Arquivos Relacionados

ArquivoFunção
{path}{function}

Estrutura da Skill

.claude/skills/{SKILL_NAME}/
├── SKILL.md
├── docs/
│   ├── {SKILL_NAME}-skill-guide.md
│   ├── {SKILL_NAME}-skill-guide.html
│   └── sections/
│       ├── 00-head.html
│       └── ...
``` #### 94-steps.html ```html

{N}. Tabela Resumo de Steps

StepNomeDescriçãoCondicional?
1{Name}{Description}Sempre
2{Name}{Description}Se {condition}
``` #### 96-rules.html ```html

{N}. Regras Críticas

  1. {Rule 1}
  2. {Rule 2}
``` #### 99-footer.html ```html ``` ### HTML Rules 1. **Use the shared CSS** — `` 2. **Use the shared Mermaid config** — `` 4. **NEVER embed CSS inline** in section files — all styling comes from the shared CSS 5. **NEVER embed Mermaid initialization** in section files — use the shared JS 6. **Section files contain ONLY body content** (except 00-head.html which includes DOCTYPE/head) 7. **Every section ends with `
`** except 00-head, 01-toc, 96-rules, and 99-footer 8. **Colored tags** for status: `SIM`, `tag-red`, `tag-orange`, `tag-blue`, `tag-purple`, `tag-cyan`, `tag-pink` 9. **ALWAYS write content in Brazilian Portuguese with correct accents** ### Color Palette (reference) | Variable | Color | Usage | |----------|-------|-------| | `--accent` | `#58a6ff` | h2 titles, links, numbered badges | | `--purple` | `#bc8cff` | h3 titles, iOS tags | | `--green` | `#3fb950` | SIM tags, success, Android | | `--red` | `#f85149` | NÃO tags, error, failure | | `--orange` | `#d29922` | PERGUNTAR tags, warning | | `--cyan` | `#39d2c0` | Inline code, actions | | `--pink` | `#f778ba` | Special tags | ### Card Colors by Type Use `border-left: 3px solid {color}` to differentiate cards: - Detection/Analysis: `card-detect` (blue) - Bump/Build/Deploy: `card-bump` (green) - Labels/Tags: `card-label` (purple) - Jira/Integration: `card-jira` (orange) - Template/Docs: `card-template` (cyan) - Changelog/History: `card-changelog` (pink) --- ## Step 6: Build HTML Run the build script to assemble the final HTML from sections: ```bash $SKILL_DIR/build.sh {skill-name} ``` `build.sh` locates the target skill's `docs/sections/` under `.claude/skills`, `.agents/skills`, `~/.claude/skills`, or `~/.agents/skills`, and rewrites theme asset paths so CSS/JS resolve from wherever `skill-doc` is installed. This concatenates all `docs/sections/*.html` files (sorted by name) into `docs/{skill-name}-skill-guide.html`. **Verify** the output exists and has reasonable size (should be smaller than legacy monolithic files since CSS is external). --- ## Step 7: Show Result ### Mode: create ``` Documentation generated: - {skill-dir}/docs/{skill-name}-skill-guide.md - {skill-dir}/docs/{skill-name}-skill-guide.html (built from {N} sections) Sections: {count} Scenarios: {count} Steps documented: {count} Rules documented: {count} ``` ### Mode: update ``` Documentation updated: - {skill-dir}/docs/{skill-name}-skill-guide.md (updated) - {skill-dir}/docs/{skill-name}-skill-guide.html (rebuilt) Sections updated: {list of updated section files} Sections unchanged: {list of kept section files} Sections added: {list of new section files, if any} Sections removed: {list of removed section files, if any} ``` ### Mode: migrate ``` Documentation migrated to section-based format: - {skill-dir}/docs/{skill-name}-skill-guide.md (kept) - {skill-dir}/docs/{skill-name}-skill-guide.html (rebuilt from sections) - {skill-dir}/docs/sections/ ({N} section files created) Legacy monolithic HTML replaced by section-based build. ``` --- ## Rules 1. **ALWAYS write generated docs in Brazilian Portuguese** with correct accents (é, ã, ç, etc.) 2. **ALWAYS use the shared CSS** (`theme/skill-doc.css`) — NEVER embed CSS in section files 3. **ALWAYS use the shared Mermaid config** (`theme/skill-doc-mermaid.js`) — NEVER embed mermaid.initialize() in sections 4. **ALWAYS run `build.sh`** after generating or updating sections to assemble the final HTML 5. **ALWAYS include Mermaid.js** for diagrams in HTML (do not use ASCII in HTML) 6. **ALWAYS include a table of contents** (`01-toc.html`) in HTML 7. **ALWAYS document ALL steps** of the skill — do not skip any 8. **ALWAYS include example scenarios** (minimum 3) 9. **ALWAYS include the steps summary table** at the end 10. **NEVER invent features** that don't exist in the skill — document only what is in the SKILL.md 11. **NEVER omit rules** — all skill rules must appear in the documentation 12. **NEVER create sections without the correct numeric prefix** — follow the numbering convention 13. The .md and .html content must be equivalent (same content, different formats) 14. If the skill has a `references/` folder, include the relevant content in the documentation 15. Adapt the number and type of custom sections (10–89 range) to the skill's content 16. In **update mode**, regenerate `01-toc.html` whenever sections are added or removed 17. In **update mode**, report to the user exactly which sections changed and which were kept