generate-docs

Name: generate-docs
Author: gtrabanco

23installs2forks

How to install generate-docs?

gtrabanco/agentic-workflow/generate-docs

$npx -y skills add gtrabanco/agentic-workflow --skill generate-docs

Installs into the current project.

Summary

Generate or update incremental developer documentation in the target project's own docs site: diff-driven how-to guides for what a unit of work changed, written through a discovered docs adapter (Starlight/Astro MDX is the first-class reference; plain markdown is the always-avail

Files · 1

View on GitHub

SKILL.md

1	# Generate Docs
2
3	Turn the knowledge produced by a unit of work into developer documentation a
4	contributor can read on the project's docs website — incrementally, as a
5	by-product of shipping, so a public repo's docs stay current instead of
6	rotting. A commit says what changed; a guide says how to use it ("how do I
7	create a domain event and where do I register its handler").
8
9	## Turn contract — verify before ending the turn
10
11	```
12	✓ The docs adapter was resolved through the Step 0 detection checklist and the
13	outcome (adapter name, or NOT CONFIGURED) is stated in the report
14	✓ Every generated/updated page is WRITTEN to disk (paths listed in the report)
15	and carries the provenance frontmatter — or zero pages were written and the
16	report says exactly why
17	✓ The verify step was RUN (docs build command or link check) and its result
18	pasted — never assumed
19	✓ Artifact language: explicit user instruction > the project's declared docs
20	language > English. The CONVERSATION language never decides
21	✓ The fixed report block is printed, then the closing `→ Next:` block, as the
22	ABSOLUTE last output
23	```
24
25	About to end the turn with any box unchecked? The turn is NOT done — complete
26	the missing box first (weak models drop end-of-document duties; this list is
27	first on purpose).
28
29	## When to use
30
31	- After finishing a unit of work — `execute-phase` recommends this skill at
32	close-out when the project declares a docs site: document what the unit
33	changed while the context is fresh.
34	- On demand for a specific area: `generate-docs src/domain/events/`.
35	- `--review` — export the latest `review-change` report as a docs page so
36	humans can review findings from the website.
37	- Not for writing SPECs/planning docs (`plan-feature`), session journals
38	(`log-session`), or reviewing code (`review-change` produces the findings;
39	this skill only publishes an existing report on request).
40
41	## Step 0 — Discover the project (always first)
42
43	Per the agent guide's Workflow conventions + documentation map, then
44	resolve the docs adapter with this checklist — fixed order, first match
45	wins, evidence required for the match:
46
47	1. Explicit declaration — the documentation map contains a `Docs site`
48	block (format, content dir, build command, map command). Evidence: quote
49	the block. → use the declared adapter.
50	2. Starlight — an `astro.config.*` exists AND `@astrojs/starlight` is in
51	the project's dependencies. Evidence: config path + the dependency line.
52	→ Starlight adapter.
53	3. Docusaurus — a `docusaurus.config.*` exists AND `@docusaurus/core` is a
54	dependency. Evidence: config path + the dependency line. → Docusaurus
55	adapter (same slots as Starlight; `.mdx` under the site's `docs/` dir,
56	sidebar per its convention).
57	4. Plain-markdown fallback — a `docs/` directory exists. → plain-markdown
58	adapter (always available).
59	5. None of the above → NOT CONFIGURED: write nothing. Print the report
60	with `Decision: NOT-CONFIGURED`, and include this snippet for the user to
61	add to their documentation map:
62
63	```markdown
64	## Docs site
65	- format: starlight \| docusaurus \| markdown
66	- content-dir: <path, e.g. src/content/docs/>
67	- build: <command, e.g. npx astro check \| none>
68	- map: <command emitting a nodes/edges JSON \| none>
69	```
70
71	Detection is per invocation — never cached, never guessed. A monorepo with
72	more than one docs site is a documented limitation: use the first declaration
73	found and say so in the report (see the feature's `known-issues.md`).
74
75	## Process
76
77	1. Resolve the scope — exactly one of, in this order:
78	- an explicit argument (`NN-slug`, `fix-n`, or a path/glob) → that unit's
79	branch diff vs the default branch, or the given paths;
80	- no argument → the current branch's diff vs the default branch;
81	- on the default branch with a clean tree → the last merged unit's diff
82	(`git log --merges -1` → its diff). State the resolved scope in the
83	report.
84
85	2. **Sele

People who liked this also viewed

6 picks

Type

generate-docs

23installs2forks

View on GitHub

How to install generate-docs?

gtrabanco/agentic-workflow/generate-docs

$npx -y skills add gtrabanco/agentic-workflow --skill generate-docs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Generate Docs
2
3	Turn the knowledge produced by a unit of work into developer documentation a
4	contributor can read on the project's docs website — incrementally, as a
5	by-product of shipping, so a public repo's docs stay current instead of
6	rotting. A commit says what changed; a guide says how to use it ("how do I
7	create a domain event and where do I register its handler").
8
9	## Turn contract — verify before ending the turn
10
11	```
12	✓ The docs adapter was resolved through the Step 0 detection checklist and the
13	outcome (adapter name, or NOT CONFIGURED) is stated in the report
14	✓ Every generated/updated page is WRITTEN to disk (paths listed in the report)
15	and carries the provenance frontmatter — or zero pages were written and the
16	report says exactly why
17	✓ The verify step was RUN (docs build command or link check) and its result
18	pasted — never assumed
19	✓ Artifact language: explicit user instruction > the project's declared docs
20	language > English. The CONVERSATION language never decides
21	✓ The fixed report block is printed, then the closing `→ Next:` block, as the
22	ABSOLUTE last output
23	```
24
25	About to end the turn with any box unchecked? The turn is NOT done — complete
26	the missing box first (weak models drop end-of-document duties; this list is
27	first on purpose).
28
29	## When to use
30
31	- After finishing a unit of work — `execute-phase` recommends this skill at
32	close-out when the project declares a docs site: document what the unit
33	changed while the context is fresh.
34	- On demand for a specific area: `generate-docs src/domain/events/`.
35	- `--review` — export the latest `review-change` report as a docs page so
36	humans can review findings from the website.
37	- Not for writing SPECs/planning docs (`plan-feature`), session journals
38	(`log-session`), or reviewing code (`review-change` produces the findings;
39	this skill only publishes an existing report on request).
40
41	## Step 0 — Discover the project (always first)
42
43	Per the agent guide's Workflow conventions + documentation map, then
44	resolve the docs adapter with this checklist — fixed order, first match
45	wins, evidence required for the match:
46
47	1. Explicit declaration — the documentation map contains a `Docs site`
48	block (format, content dir, build command, map command). Evidence: quote
49	the block. → use the declared adapter.
50	2. Starlight — an `astro.config.*` exists AND `@astrojs/starlight` is in
51	the project's dependencies. Evidence: config path + the dependency line.
52	→ Starlight adapter.
53	3. Docusaurus — a `docusaurus.config.*` exists AND `@docusaurus/core` is a
54	dependency. Evidence: config path + the dependency line. → Docusaurus
55	adapter (same slots as Starlight; `.mdx` under the site's `docs/` dir,
56	sidebar per its convention).
57	4. Plain-markdown fallback — a `docs/` directory exists. → plain-markdown
58	adapter (always available).
59	5. None of the above → NOT CONFIGURED: write nothing. Print the report
60	with `Decision: NOT-CONFIGURED`, and include this snippet for the user to
61	add to their documentation map:
62
63	```markdown
64	## Docs site
65	- format: starlight \| docusaurus \| markdown
66	- content-dir: <path, e.g. src/content/docs/>
67	- build: <command, e.g. npx astro check \| none>
68	- map: <command emitting a nodes/edges JSON \| none>
69	```
70
71	Detection is per invocation — never cached, never guessed. A monorepo with
72	more than one docs site is a documented limitation: use the first declaration
73	found and say so in the report (see the feature's `known-issues.md`).
74
75	## Process
76
77	1. Resolve the scope — exactly one of, in this order:
78	- an explicit argument (`NN-slug`, `fix-n`, or a path/glob) → that unit's
79	branch diff vs the default branch, or the given paths;
80	- no argument → the current branch's diff vs the default branch;
81	- on the default branch with a clean tree → the last merged unit's diff
82	(`git log --merges -1` → its diff). State the resolved scope in the
83	report.
84
85	2. **Sele

People who liked this also viewed

6 picks

Type