thgMatajs 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 <skill-name>.
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
AskUserQuestionto 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.cssandtheme/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 # <!DOCTYPE> + <head> + <body> 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 # </body></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
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)
If not found, ask the user for the correct path or name.
Read the full
SKILL.mdof the found skill.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:
- Metadata: name, description, arguments, allowed tools
- Steps/Phases: list each step with name, description, and whether it is conditional
- Rules: all critical rules and restrictions
- Tools: which MCPs, CLIs, scripts, and tools are used
- Files: which project files the skill reads or modifies
- Conditional decisions: where the skill asks the user or makes context-based decisions
- 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
# 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
- ALWAYS write in Brazilian Portuguese with correct accents (é, ã, ç, ú, etc.)
- Use tables for structured data
- Use ASCII diagrams for flows (inside ``` blocks)
- Use inline
codefor file names, commands, variables - Use bold for emphasis on rules and important terms
- Minimum 3 example scenarios, ideal 5
- 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
- Read each existing section file
- Compare content against the current SKILL.md analysis (Step 3)
- Identify which sections are stale (content no longer matches SKILL.md)
- Regenerate ONLY the stale sections using
Write(for new) orEdit(for partial changes) - If sections were added or removed → always regenerate
01-toc.html - Report to the user which sections were updated and which were kept
Mode: migrate
- Read the legacy monolithic HTML file
- Extract the content sections from it
- Generate all section files from the extracted content
- The legacy HTML is overwritten by
build.shoutput
Section Templates
00-head.html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Skill {SKILL_TITLE} — Guia Completo</title>
<link rel="stylesheet" href="../../skill-doc/theme/skill-doc.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script src="../../skill-doc/theme/skill-doc-mermaid.js"></script>
</head>
<body>
<h1><span>/{SKILL_NAME}</span> — Guia Completo</h1>
<p class="subtitle">{SUBTITLE}</p>
01-toc.html
<nav class="toc">
<h3>Sumário</h3>
<ol>
<li><a href="#overview">Visão Geral</a></li>
<li><a href="#main-flow">Fluxo Completo</a></li>
<!-- Skill-specific section links here -->
<li><a href="#scenarios">Cenários e Exemplos</a></li>
<li><a href="#tools">Ferramentas e Arquivos</a></li>
<li><a href="#steps-table">Tabela Resumo de Steps</a></li>
<li><a href="#rules">Regras Críticas</a></li>
</ol>
</nav>
02-overview.html
<h2 id="overview">1. Visão Geral</h2>
<p>{Description}</p>
<div class="card-grid">
<div class="card card-detect"><h4><span class="icon">🔍</span> {Feature}</h4><p>{Description}</p></div>
<!-- More cards... Card types: card-detect (blue), card-bump (green), card-label (purple), card-jira (orange), card-template (cyan), card-changelog (pink) -->
</div>
<h3>Formas de Invocação</h3>
<pre><code>/{SKILL_NAME} arg1 # Description</code></pre>
<hr class="divider">
03-flow.html
<h2 id="main-flow">2. Fluxo Completo</h2>
<div class="mermaid">
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
</div>
<hr class="divider">
10-{custom}.html through 89-{custom}.html (skill-specific)
<h2 id="{section-id}">{N}. {Section Title}</h2>
<p>{Explanation}</p>
<table>
<tr><th>Column 1</th><th>Column 2</th><th>Status</th></tr>
<tr><td>Value</td><td>Value</td><td><span class="tag tag-green">SIM</span></td></tr>
</table>
<hr class="divider">
90-scenarios.html
<h2 id="scenarios">{N}. Cenários e Exemplos</h2>
<div class="scenario-box">
<div class="label">Cenário 1 — {Short description}</div>
<div class="flow">
<span class="action">Entrada:</span> /{SKILL_NAME} args<br>
<span class="action">Contexto:</span> {context}<br>
<span class="result">Resultado:</span> {result}<br>
</div>
</div>
<!-- Flow classes: .action (cyan), .result (green), .warn (orange), .error (red), .skip (muted) -->
<hr class="divider">
92-tools.html
<h2 id="tools">{N}. Ferramentas e Arquivos</h2>
<h3>Ferramentas Utilizadas</h3>
<table>
<tr><th>Ferramenta</th><th>Função</th><th>Usada em</th></tr>
<tr><td><code>{tool}</code></td><td>{function}</td><td>{steps}</td></tr>
</table>
<h3>Arquivos Relacionados</h3>
<table>
<tr><th>Arquivo</th><th>Função</th></tr>
<tr><td><code>{path}</code></td><td>{function}</td></tr>
</table>
<h3>Estrutura da Skill</h3>
<pre><code>.claude/skills/{SKILL_NAME}/
├── SKILL.md
├── docs/
│ ├── {SKILL_NAME}-skill-guide.md
│ ├── {SKILL_NAME}-skill-guide.html
│ └── sections/
│ ├── 00-head.html
│ └── ...</code></pre>
<hr class="divider">
94-steps.html
<h2 id="steps-table">{N}. Tabela Resumo de Steps</h2>
<table>
<tr><th>Step</th><th>Nome</th><th>Descrição</th><th>Condicional?</th></tr>
<tr><td>1</td><td>{Name}</td><td>{Description}</td><td><span class="tag tag-blue">Sempre</span></td></tr>
<tr><td>2</td><td>{Name}</td><td>{Description}</td><td><span class="tag tag-orange">Se {condition}</span></td></tr>
</table>
<hr class="divider">
96-rules.html
<h2 id="rules">{N}. Regras Críticas</h2>
<ol class="rules-list">
<li>{Rule 1}</li>
<li>{Rule 2}</li>
</ol>
99-footer.html
</body>
</html>
HTML Rules
- Use the shared CSS —
<link rel="stylesheet" href="../../skill-doc/theme/skill-doc.css"> - Use the shared Mermaid config —
<script src="../../skill-doc/theme/skill-doc-mermaid.js"> - Mermaid.js CDN in head —
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script> - NEVER embed CSS inline in section files — all styling comes from the shared CSS
- NEVER embed Mermaid initialization in section files — use the shared JS
- Section files contain ONLY body content (except 00-head.html which includes DOCTYPE/head)
- Every section ends with
<hr class="divider">except 00-head, 01-toc, 96-rules, and 99-footer - Colored tags for status:
<span class="tag tag-green">SIM</span>,tag-red,tag-orange,tag-blue,tag-purple,tag-cyan,tag-pink - 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:
$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
- ALWAYS write generated docs in Brazilian Portuguese with correct accents (é, ã, ç, etc.)
- ALWAYS use the shared CSS (
theme/skill-doc.css) — NEVER embed CSS in section files - ALWAYS use the shared Mermaid config (
theme/skill-doc-mermaid.js) — NEVER embed mermaid.initialize() in sections - ALWAYS run
build.shafter generating or updating sections to assemble the final HTML - ALWAYS include Mermaid.js for diagrams in HTML (do not use ASCII in HTML)
- ALWAYS include a table of contents (
01-toc.html) in HTML - ALWAYS document ALL steps of the skill — do not skip any
- ALWAYS include example scenarios (minimum 3)
- ALWAYS include the steps summary table at the end
- NEVER invent features that don't exist in the skill — document only what is in the SKILL.md
- NEVER omit rules — all skill rules must appear in the documentation
- NEVER create sections without the correct numeric prefix — follow the numbering convention
- The .md and .html content must be equivalent (same content, different formats)
- If the skill has a
references/folder, include the relevant content in the documentation - Adapt the number and type of custom sections (10–89 range) to the skill's content
- In update mode, regenerate
01-toc.htmlwhenever sections are added or removed - In update mode, report to the user exactly which sections changed and which were kept