Lintel on GitHub Copilot. Generated from skills/generate-docs/SKILL.md; edit the canonical file, then run
li-copilot init.
- Resource root:
../../.. from this skill's base directory (the Lintel source with bin/,
lib/, skills/). Write plans, state and evidence into the working repository's .claude/
tree, never into the resource root.
- Skill-relative paths: this skill's own
scripts/, references/ and data/ folders (and a
<base> that the workflow defines as its own directory) mean
../../../skills/generate-docs/ in the Lintel source, not this generated folder.
${LINTEL_SKILLS_DIR:-skills} means the skills root, ../../../skills. A bin/li-run step
runs in the working repository, so use $LINTEL_SKILLS_DIR/generate-docs/ there.
- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exe on Windows, never
System32\bash.exe). Save a snippet to a temporary .sh file and run
bash "<resource root>/bin/li-run" <file>; it prepares LINTEL_SOURCE_ROOT, LINTEL_REPO_ROOT
and the profile context.
- Tools: Read=
view, Write=create, Edit=edit, Bash=bash/powershell, Grep=grep,
Glob=glob, AskUserQuestion=ask_user, TodoWrite=the plan checklist, Task or a named role=task
with that custom agent, WebFetch=web_fetch.
- Other Lintel workflows are native skills: invoke
/li-<name> rather than reading their
files. Named roles such as CodeReviewer are custom agents.
/generate-docs
Generate Markdown documentation from selected source code and its actual behavior.
Keep engineering reference, customer-guide and tutorial outcomes. This is distinct
from the DocWriter method for detecting drift and revising existing documentation,
and from generate, which renders a content brief into document formats.
Both documentation front doors directly consume BUILD's
documentation-fidelity method.
Neither delegates its checks to the other.
Inputs
| Input |
Contract |
--source <path-or-glob> |
Required selected source files within the authorized repository; expand and retain the exact set |
--target <reference|customer-guide|tutorial> |
Required documentation type |
--voice <internal|pack> |
Reference/tutorial default internal; customer-guide uses the actual configured customer-facing voice when available |
--out <path> |
Default docs/<source-stem>.md, docs/guides/<source-stem>.md or docs/tutorials/<source-stem>.md respectively |
--depth <shallow|deep> |
Shallow documents public signatures and concise behavior; deep adds examples, edge cases, caveats and relevant internal helpers |
These are skill inputs, not a bundled parser. Reject missing, unknown, duplicate
or conflicting options before writing. For a multi-root glob without one source
stem, choose an explicit output instead of inventing an ambiguous default.
An existing output requires an authorized overwrite, append or alternate path.
Never silently concatenate a second reference into an existing document.
Workflow
Read sources and authority. Validate the selected map, original task and
P07 profile when supplied. Use rooted, no-link source reads. Expand the source
list before writing; read the complete selected files and their relevant
imports, types and public exports. Missing/unreadable files remain failures,
not empty modules. Do not execute imported source code merely to document it.
Read behavior evidence. Apply the shared documentation-fidelity source
inventory and intent rules to sibling tests, callers, accepted docs and
relevant local history. Retain cited signatures/defaults, return/errors,
side effects and constraints. Do not rewrite accepted intent to conceal a
code defect; the shared method also owns frozen paths and removed-option migration.
Draft the selected target without losing meaning.
| Target |
Retained structure |
| reference |
Module overview, public API table, per-export signature/parameters/return/errors/examples, related-module links; deep mode includes relevant internals and edge cases |
| customer-guide |
Purpose, useful task-oriented sections, common pitfalls, limitations and next steps; mark DRAFT pending actual distribution controls |
| tutorial |
Outcome, prerequisites, numbered what/why/command/expected-result steps, common failures/recovery and continuation paths |
Preserve facts, code examples, table values, units, citations, assumptions and
material limitations. Do not turn an example response into a guaranteed API
response or invent a "successful" command output. Label illustrative output.
Section counts are a presentation choice, never a reason to drop source detail.
Check coverage and policy. Use the shared method's claim-to-source
coverage record for every in-scope export/claim and documentation section.
Distinguish checked, unrun and divergent claims, preserving actual command/
exit evidence and missing examples. Apply the actual configured data/voice
controls; do not invent a neutral gate or infer hook activation from files.
Publish atomically. Write only the selected output within ownership, retain
the original preimage if replacement was authorized, and read it back.
Keep source identities and coverage in the run report. Customer-guide or
pack-voice output stays DRAFT until its applicable controls actually pass.
Generation never uploads or distributes the artifact.
Report. Return source/output paths, target, chosen depth/voice, coverage,
grounded examples, actual checks, failures and limitations. File size, an
empty issue list and a polished voice do not prove source fidelity.
Format handoff
The generated Markdown can become the explicit complete brief for generate
or a standalone generate-word, generate-ppt, generate-web, generate-pdf
or generate-xlsx route. Keep the original code/evidence sources selected as
provenance. Do not rename a documentation file to content.md and claim the
shared pipeline already ran.
For an actual pipeline follow the existing
source-fidelity and input admission
procedure: retain brief.md, outline.md, content.md, speaker-notes.md when
needed, design-spec.json and their existing hash/section contracts. No new
interchange schema or document layout projection is introduced.
Word editability, slide notes/rendering, workbook formula/recalculation/reopen and
PDF print/page inspection remain format-specific observations. The PDF writer
remains available, but no removed reader is restored; unavailable inspection
stays unverified. Documentation generation cannot clear another format's gates.
Failure boundaries
- No public exports: clarify whether internal helpers are the desired scope;
do not fabricate a public API.
- Missing optional tests: retain source-grounded documentation and mark examples
unverified. Missing required behavior evidence blocks the affected claim.
- Required profile/voice/data control missing or failed: block that action; no
silent neutral fallback or invented customer-facing voice.
- Unavailable optional voice corpus: retain an explicitly unvalidated DRAFT, not
a distribution-ready guide or an instruction to install personal tooling.
- Changed source during generation: refresh the affected coverage and evidence
before publication. Do not reuse stale source hashes or review decisions.
Apply the same shared method to later changed-source coverage; it does not require
a DocWriter handoff. lessons-add remains available for an explicitly authorized
reusable documentation lesson, never an automatic persistence step.
1---2name: li-generate-docs3description: Use to generate source-grounded reference documentation, customer guides or onboarding tutorials while retaining API behavior, examples, provenance and limitations.4metadata:5 source: https://skillmd.com/skills/jokerman89/li-generate-docs6---78> **Lintel on GitHub Copilot.** Generated from `skills/generate-docs/SKILL.md`; edit the canonical file, then run9> `li-copilot init`.10> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,11> `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`12> tree, never into the resource root.13> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a14> `<base>` that the workflow defines as its own directory) mean15> `../../../skills/generate-docs/` in the Lintel source, not this generated folder.16> `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step17> runs in the working repository, so use `$LINTEL_SKILLS_DIR/generate-docs/` there.18> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never19> `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run20> `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`21> and the profile context.22> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,23> Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`24> with that custom agent, WebFetch=`web_fetch`.25> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their26> files. Named roles such as `CodeReviewer` are custom agents.2728# /generate-docs2930Generate Markdown documentation from selected source code and its actual behavior.31Keep engineering reference, customer-guide and tutorial outcomes. This is distinct32from the `DocWriter` method for detecting drift and revising existing documentation,33and from `generate`, which renders a content brief into document formats.34Both documentation front doors directly consume BUILD's35[documentation-fidelity method](../../../skills/build/references/documentation-fidelity.md).36Neither delegates its checks to the other.3738## Inputs3940| Input | Contract |41|---|---|42| `--source <path-or-glob>` | Required selected source files within the authorized repository; expand and retain the exact set |43| `--target <reference\|customer-guide\|tutorial>` | Required documentation type |44| `--voice <internal\|pack>` | Reference/tutorial default internal; customer-guide uses the actual configured customer-facing voice when available |45| `--out <path>` | Default `docs/<source-stem>.md`, `docs/guides/<source-stem>.md` or `docs/tutorials/<source-stem>.md` respectively |46| `--depth <shallow\|deep>` | Shallow documents public signatures and concise behavior; deep adds examples, edge cases, caveats and relevant internal helpers |4748These are skill inputs, not a bundled parser. Reject missing, unknown, duplicate49or conflicting options before writing. For a multi-root glob without one source50stem, choose an explicit output instead of inventing an ambiguous default.51An existing output requires an authorized overwrite, append or alternate path.52Never silently concatenate a second reference into an existing document.5354## Workflow55561. **Read sources and authority.** Validate the selected map, original task and57 P07 profile when supplied. Use rooted, no-link source reads. Expand the source58 list before writing; read the complete selected files and their relevant59 imports, types and public exports. Missing/unreadable files remain failures,60 not empty modules. Do not execute imported source code merely to document it.612. **Read behavior evidence.** Apply the shared documentation-fidelity source62 inventory and intent rules to sibling tests, callers, accepted docs and63 relevant local history. Retain cited signatures/defaults, return/errors,64 side effects and constraints. Do not rewrite accepted intent to conceal a65 code defect; the shared method also owns frozen paths and removed-option migration.663. **Draft the selected target without losing meaning.**6768 | Target | Retained structure |69 |---|---|70 | reference | Module overview, public API table, per-export signature/parameters/return/errors/examples, related-module links; deep mode includes relevant internals and edge cases |71 | customer-guide | Purpose, useful task-oriented sections, common pitfalls, limitations and next steps; mark DRAFT pending actual distribution controls |72 | tutorial | Outcome, prerequisites, numbered what/why/command/expected-result steps, common failures/recovery and continuation paths |7374 Preserve facts, code examples, table values, units, citations, assumptions and75 material limitations. Do not turn an example response into a guaranteed API76 response or invent a "successful" command output. Label illustrative output.77 Section counts are a presentation choice, never a reason to drop source detail.784. **Check coverage and policy.** Use the shared method's claim-to-source79 coverage record for every in-scope export/claim and documentation section.80 Distinguish checked, unrun and divergent claims, preserving actual command/81 exit evidence and missing examples. Apply the actual configured data/voice82 controls; do not invent a neutral gate or infer hook activation from files.835. **Publish atomically.** Write only the selected output within ownership, retain84 the original preimage if replacement was authorized, and read it back.85 Keep source identities and coverage in the run report. Customer-guide or86 pack-voice output stays DRAFT until its applicable controls actually pass.87 Generation never uploads or distributes the artifact.886. **Report.** Return source/output paths, target, chosen depth/voice, coverage,89 grounded examples, actual checks, failures and limitations. File size, an90 empty issue list and a polished voice do not prove source fidelity.9192## Format handoff9394The generated Markdown can become the explicit complete brief for `generate`95or a standalone `generate-word`, `generate-ppt`, `generate-web`, `generate-pdf`96or `generate-xlsx` route. Keep the original code/evidence sources selected as97provenance. Do not rename a documentation file to `content.md` and claim the98shared pipeline already ran.99100For an actual pipeline follow the existing101[source-fidelity and input admission](../../../skills/generate-write/references/fidelity-and-evidence.md)102procedure: retain `brief.md`, `outline.md`, `content.md`, `speaker-notes.md` when103needed, `design-spec.json` and their existing hash/section contracts. No new104interchange schema or document layout projection is introduced.105106Word editability, slide notes/rendering, workbook formula/recalculation/reopen and107PDF print/page inspection remain format-specific observations. The PDF writer108remains available, but no removed reader is restored; unavailable inspection109stays unverified. Documentation generation cannot clear another format's gates.110111## Failure boundaries112113- No public exports: clarify whether internal helpers are the desired scope;114 do not fabricate a public API.115- Missing optional tests: retain source-grounded documentation and mark examples116 unverified. Missing required behavior evidence blocks the affected claim.117- Required profile/voice/data control missing or failed: block that action; no118 silent neutral fallback or invented customer-facing voice.119- Unavailable optional voice corpus: retain an explicitly unvalidated DRAFT, not120 a distribution-ready guide or an instruction to install personal tooling.121- Changed source during generation: refresh the affected coverage and evidence122 before publication. Do not reuse stale source hashes or review decisions.123124Apply the same shared method to later changed-source coverage; it does not require125a DocWriter handoff. `lessons-add` remains available for an explicitly authorized126reusable documentation lesson, never an automatic persistence step.