absolute-docs

Name: absolute-docs
Author: maddhruv

199stars32forks

How to install absolute-docs?

maddhruv/absolute/absolute-docs

$npx -y skills add maddhruv/absolute --skill absolute-docs

Installs into the current project.

Summary

Diátaxis-driven documentation for AI coding agents: write, improve, or audit tutorials, how-tos, reference, explanation, and developer docs (README, CONTRIBUTING, ADRs). Detects the docs stack; gates on the outline before writing prose; verifies every claim against the code befor

Files · 1

View on GitHub

SKILL.md

1	> Start your first response with the 📚 emoji.
2
3	## Absolute Documentations: Diátaxis-Driven Documentation
4
5	Absolute Documentations turns "write some docs" into documentation a reader can
6	actually use. Every document it produces serves exactly one reader need, identified
7	with the Diátaxis framework, written in the project's own voice and docs stack, and
8	verified against the actual codebase before it ships. It writes new docs, rewrites
9	existing ones to their quadrant's standard, and audits whole doc sites for
10	structural rot.
11
12	It never writes a full document before the outline is approved, and it never
13	documents behavior it has not verified in the code.
14
15	---
16
17	## The Diátaxis Compass
18
19	Every piece of documentation answers exactly one kind of reader need. Classify
20	before writing — a page that mixes quadrants serves nobody.
21
22	\| \| Serves the reader's STUDY \| Serves the reader's WORK \|
23	\|---\|---\|---\|
24	\| Practical steps \| Tutorial — a lesson. Guides a newcomer through a guaranteed-success experience. \| How-to guide — a recipe. Helps a competent user accomplish a specific goal. \|
25	\| Theoretical knowledge \| Explanation — a discussion. Deepens understanding of a topic, gives context and reasons. \| Reference — a dictionary. States facts about the machinery, completely and neutrally. \|
26
27	To classify, ask two questions:
28
29	1. Is the reader studying (acquiring skill) or working (applying skill)?
30	2. Does the reader need action (steps to follow) or cognition (knowledge to absorb)?
31
32	\| Reader situation \| Quadrant \|
33	\|---\|---\|
34	\| "I'm new, show me what this is like" \| Tutorial \|
35	\| "I know the basics, I need to get X done" \| How-to guide \|
36	\| "What exactly does this option/endpoint/flag do?" \| Reference \|
37	\| "Why does it work this way? What's the bigger picture?" \| Explanation \|
38
39	The cardinal sin is mixing. A tutorial that stops to explain architecture loses
40	the learner. A reference page that gives advice stops being trustworthy as a pure
41	description. When you feel the urge to mix, that is a signal to link to the other
42	quadrant, not to merge into it.
43
44	---
45
46	## Modes
47
48	Detect the mode from the request:
49
50	\| User says \| Mode \|
51	\|---\|---\|
52	\| "write a tutorial / guide / README / docs for X", "document this feature" \| WRITE \|
53	\| "improve / rewrite / clean up this doc", "this README is bad" \| IMPROVE \|
54	\| "audit our docs", "our docs are a mess", "restructure the documentation" \| AUDIT \|
55
56	---
57
58	## WRITE Mode
59
60	### Step 1 — Recon (codebase first, questions second)
61
62	Before asking the user anything, learn everything the repo can teach:
63
64	- Detect the docs stack (see Stack Detection below) and load
65	`references/docs-stacks.md` if writing site pages.
66	- Read existing docs — tone, terminology, heading style, frontmatter schema,
67	sidebar/nav structure, where each quadrant lives.
68	- Read the code being documented — public API surface, actual option names,
69	actual defaults, actual error messages. The code is the source of truth, not
70	your memory of similar tools.
71	- Check project metadata — package.json/pyproject/go.mod for the real name,
72	version, install command, supported runtimes.
73
74	### Step 2 — Intake
75
76	Four things must be pinned down before any outline. Answer them from recon where
77	possible; ask the user only what the repo cannot answer, one question at a
78	time (use `AskUserQuestion` where available), always with a recommended answer:
79
80	1. Document type — which Diátaxis quadrant (or which developer-doc form).
81	2. Target audience — novice end user? experienced operator? contributor?
82	What can you assume they already know?
83	3. Reader's goal — what will the reader be able to do after reading?
84	4. Scope — what is explicitly in, and just as important, what is explicitly out.
85
86	### Step 3 — Outline gate (hard gate)
87
88	Propose, before writing any prose:
89
90	- the file path(s) the doc will live at, matching the stack's routing conventions
91	- a heading-level outline with one line per section describing its content
92	- the quadrant each page serves (multi-page requests get one quadrant per page)
93	- any sidebar/nav changes needed
94
95	STOP and wait for explicit approval. Do not write the document until the user
96	confirms the outline. This

People who liked this also viewed

6 picks

Type

absolute-docs

199stars32forks

View on GitHub

How to install absolute-docs?

maddhruv/absolute/absolute-docs

$npx -y skills add maddhruv/absolute --skill absolute-docs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	> Start your first response with the 📚 emoji.
2
3	## Absolute Documentations: Diátaxis-Driven Documentation
4
5	Absolute Documentations turns "write some docs" into documentation a reader can
6	actually use. Every document it produces serves exactly one reader need, identified
7	with the Diátaxis framework, written in the project's own voice and docs stack, and
8	verified against the actual codebase before it ships. It writes new docs, rewrites
9	existing ones to their quadrant's standard, and audits whole doc sites for
10	structural rot.
11
12	It never writes a full document before the outline is approved, and it never
13	documents behavior it has not verified in the code.
14
15	---
16
17	## The Diátaxis Compass
18
19	Every piece of documentation answers exactly one kind of reader need. Classify
20	before writing — a page that mixes quadrants serves nobody.
21
22	\| \| Serves the reader's STUDY \| Serves the reader's WORK \|
23	\|---\|---\|---\|
24	\| Practical steps \| Tutorial — a lesson. Guides a newcomer through a guaranteed-success experience. \| How-to guide — a recipe. Helps a competent user accomplish a specific goal. \|
25	\| Theoretical knowledge \| Explanation — a discussion. Deepens understanding of a topic, gives context and reasons. \| Reference — a dictionary. States facts about the machinery, completely and neutrally. \|
26
27	To classify, ask two questions:
28
29	1. Is the reader studying (acquiring skill) or working (applying skill)?
30	2. Does the reader need action (steps to follow) or cognition (knowledge to absorb)?
31
32	\| Reader situation \| Quadrant \|
33	\|---\|---\|
34	\| "I'm new, show me what this is like" \| Tutorial \|
35	\| "I know the basics, I need to get X done" \| How-to guide \|
36	\| "What exactly does this option/endpoint/flag do?" \| Reference \|
37	\| "Why does it work this way? What's the bigger picture?" \| Explanation \|
38
39	The cardinal sin is mixing. A tutorial that stops to explain architecture loses
40	the learner. A reference page that gives advice stops being trustworthy as a pure
41	description. When you feel the urge to mix, that is a signal to link to the other
42	quadrant, not to merge into it.
43
44	---
45
46	## Modes
47
48	Detect the mode from the request:
49
50	\| User says \| Mode \|
51	\|---\|---\|
52	\| "write a tutorial / guide / README / docs for X", "document this feature" \| WRITE \|
53	\| "improve / rewrite / clean up this doc", "this README is bad" \| IMPROVE \|
54	\| "audit our docs", "our docs are a mess", "restructure the documentation" \| AUDIT \|
55
56	---
57
58	## WRITE Mode
59
60	### Step 1 — Recon (codebase first, questions second)
61
62	Before asking the user anything, learn everything the repo can teach:
63
64	- Detect the docs stack (see Stack Detection below) and load
65	`references/docs-stacks.md` if writing site pages.
66	- Read existing docs — tone, terminology, heading style, frontmatter schema,
67	sidebar/nav structure, where each quadrant lives.
68	- Read the code being documented — public API surface, actual option names,
69	actual defaults, actual error messages. The code is the source of truth, not
70	your memory of similar tools.
71	- Check project metadata — package.json/pyproject/go.mod for the real name,
72	version, install command, supported runtimes.
73
74	### Step 2 — Intake
75
76	Four things must be pinned down before any outline. Answer them from recon where
77	possible; ask the user only what the repo cannot answer, one question at a
78	time (use `AskUserQuestion` where available), always with a recommended answer:
79
80	1. Document type — which Diátaxis quadrant (or which developer-doc form).
81	2. Target audience — novice end user? experienced operator? contributor?
82	What can you assume they already know?
83	3. Reader's goal — what will the reader be able to do after reading?
84	4. Scope — what is explicitly in, and just as important, what is explicitly out.
85
86	### Step 3 — Outline gate (hard gate)
87
88	Propose, before writing any prose:
89
90	- the file path(s) the doc will live at, matching the stack's routing conventions
91	- a heading-level outline with one line per section describing its content
92	- the quadrant each page serves (multi-page requests get one quadrant per page)
93	- any sidebar/nav changes needed
94
95	STOP and wait for explicit approval. Do not write the document until the user
96	confirms the outline. This

People who liked this also viewed

6 picks

Type