Menu
Generate documentation for a part of the system, derived from the code, in DOCS_DIR/. Usage: /generate-docs <area name>
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Capture reproducible UI screenshots with Playwright (against the Firebase emulators) for use in the docs. Usage: /capture-screenshots <area or shot id>
Compare the docs in DOCS_DIR/ with the current code and update the ones whose source changed.
| name | generate-docs |
| description | Generate documentation for a part of the system, derived from the code, in DOCS_DIR/. Usage: /generate-docs <area name> |
| user_invocable | true |
| model | sonnet |
Generate a new documentation file in docs/ for the given area of the system,
derived from the code — not written from memory or from a spec.
If no area name is given, ask the user which part of the system to document.
Fill in before first use (one-time, search-and-replace):
docs— where your docs live (e.g.docsordocs/domain)src, functions— the folders/globs your code lives inLanguage is English. The structure below is proven; only the specifics are yours.
If docs/<area>.md already exists, stop and point the user to /update-docs. Only overwrite
if they explicitly ask for it.
Use an Explore subagent for the broad search — you want the conclusion (which files belong to this
area), not every file's contents in your main context. Search in src, functions for:
Report which files you found and ask the user to confirm the scope before continuing.
Tip: name the doc after the folder/module the code lives in, so the Stop hook can match a changed file to its doc by that shared name and the auto-update "just works".
From the source files, pull out only what the code actually says:
Document the data model + behaviour; keep the UI / serialization layer to a brief mention in "Related code".
Read one existing file in docs/ first as a style reference (if any exist). Then write
docs/<area>.md in English, using this skeleton:
# Data Dictionary — <Area name>
## Context
<2–3 sentences: what this area is, what it's used for, who relies on it>
---
## 1. <Main entity>
<short description>
**Source:** `<relative/path>`
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| … | … | … | … |
**Validation:**
- …
---
## 2. <Next entity>
…
---
## Enums & status codes
### <EnumName>
| Value | Code | Meaning |
|-------|------|---------|
| … | … | … |
---
## How it fits together
<a Mermaid `erDiagram` (relations) or `flowchart TD` (steps) — never ASCII art>
---
## Related code
### Models
- `<path>`
### Services / rules
- `<path>`
End every document with the exact source files it was derived from. This is not optional and
not decoration — it is the contract. /update-docs reads it back to find which document a code
change affects. Fill in every relevant path.
Add the new doc to docs/README.md (the index). Create it with a short intro and a list of
docs if it doesn't exist yet.
Stakeholders read the HTML version, not the Markdown — so every docs/<area>.md gets a twin
at docs/html/<area>.html. The shared design lives in docs/html/assets/
(styles.css, app.js — copy them in once from the kit's html-assets/); those handle styling,
the table-of-contents, scrollspy, copy buttons and Mermaid — you only write the content.
Create docs/html/<area>.html from this exact shell, translating the Markdown body into it:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title><Area> — Data Dictionary</title>
<link rel="stylesheet" href="assets/styles.css">
</head>
<body>
<header class="topbar">
<a class="brand" href="index.html">📚 Documentation</a>
<span class="crumb"><Area></span>
<a class="md-link" href="../<area>.md">View Markdown</a>
</header>
<div class="layout">
<main class="content">
<p class="kicker">Data Dictionary</p>
<h1><Area></h1>
<p class="lede"><context paragraph></p>
<!-- one <section> per "## N. …" heading; see the mapping below -->
</main>
<aside class="toc"><p class="toc-title">On this page</p><nav></nav></aside>
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js" integrity="sha384-WmdflGW9aGfoBdHc4rRyWzYuAjEmDwMdGdiPNacbwfGKxBW/SO6guzuQ76qjnSlr" crossorigin="anonymous"></script>
<script src="assets/app.js"></script>
</body>
</html>
Markdown → HTML mapping:
| Markdown | HTML |
|---|---|
## N. Entity | <section><h2>N. Entity</h2> … </section> (no id — app.js adds them) |
| a table | <div class="table-wrap"><table>…</table></div> |
Yes in a Required column | <span class="badge req">Yes</span> |
No in a Required column | <span class="badge opt">No</span> |
```mermaid … ``` | <pre class="mermaid">…</pre> (keep the exact mermaid source) |
`inline code` | <code>inline code</code> |
[text](./other.md) | <a href="other.html">text</a> |
> note | <blockquote><p>note</p></blockquote> |
Do not write a table-of-contents or sidebar — app.js builds the TOC from your <h2>/<h3>.
Keep the two script tags exactly as above so the Mermaid integrity hash stays valid.
Then add a card for the new doc to docs/html/index.html inside <div class="cards" id="cards">:
<a class="card" href="<area>.html"><h3><Area></h3><p><one-line summary></p></a>
If the area would be clearer with a picture of the UI, use the capture-screenshots skill to
generate reproducible images (Playwright + the Firebase emulators) and embed them in the Markdown
and its HTML twin. Don't hand-make or paste screenshots — keep them derived from the running app.
flowchart TD for steps, erDiagram for relations).