docs
Write or revise technical documentation around one reader job: reference, operation, review, decision, or product alignment. Use for READMEs, API docs, operational how-tos, RFCs, product design docs, architecture proposals, and ADRs.
Install
npx skills add https://github.com/kriscard/Skills/tree/main/skills/writing/docs
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kriscard-skills@llmmart
git clone https://github.com/kriscard/Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kriscard/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Technical Documentation Writer
Write for the reader's job: what they came to understand, decide, or do. A technically correct doc that does not serve that job is still a failed doc.
Boundaries
- Use
blogfor publishable articles with an argument, story, or public-facing lesson. - The user-invoked
teachskill owns persistent learning workspaces and HTML lessons. - Use this skill for reference docs, team proposals, decision records, READMEs, API docs, and how-to docs whose primary purpose is work, review, or operation.
Workflow
1. Name the doc type and reader job
Identify the document type before drafting: README, API docs, how-to, RFC or architecture proposal, product design doc, or ADR.
Complete when:
- the doc type is named
- the primary audience is named
- the reader job is stated as
Reader needs to <do/decide/understand> so they can <outcome> - missing inputs are requested before drafting
2. Load the matching reference
Use the routing table below. Load every reference whose condition applies before writing. The technical-style reference is additive: load it only when the prose needs sentence-level clarity work, not merely because the document is technical.
Complete when every applicable reference has been loaded, or no reference applies and that is stated.
3. Gather the minimum context
Ask only for context needed by the reader job:
- current state and desired outcome
- constraints, dependencies, and owners
- concrete examples, commands, APIs, or decisions
- known errors, risks, alternatives, or non-goals
Complete when every required placeholder in the selected template has either source material or an
explicit TBD/question for the user.
4. Draft for use, review, or decision
Lead with what the reader needs first. Show before explaining when the reader must do something; state the decision or proposal before deep rationale when the reader must decide.
Complete when:
- the opening answers the reader job
- every section exists to help the reader do, decide, or understand something
- examples are realistic and include required setup/config/error handling when relevant
- uncertainties are marked instead of invented
5. Run the quality gate
Before delivering, verify:
- First sentence says what this is or what decision/proposal is being made
- Code examples or commands were run when an environment is available; otherwise marked unverified
- Required config, inputs, env vars, and permissions are documented
- Common errors or risks include what to do next
- Links referenced in the doc were checked when accessible
- Terminology is consistent: one name per concept
- No "simple" / "just" / "easy" for user actions
Complete when all applicable checks pass or failures are called out explicitly.
References
| Priority | Load when | Reference |
|---|---|---|
| 1 | Decision already made; capture context, decision, and consequences | references/adr-template.md |
| 1 | Change not decided; solicit review, including system design with migration concerns | references/rfc-template.md |
| 1 | Scoping new product work with goals, non-goals, user stories, and metrics | references/design-doc-template.md |
| 2 | Creating or revising a README | references/readme-guide.md |
| 2 | Creating or revising API documentation | references/api-docs-guide.md |
| 2 | Creating or revising a task-oriented how-to guide | references/how-to-guide.md |
| 3 | Technical prose needs sentence-level clarity work: reader-mode boundaries, condition/action order, common-path ordering, technical names, link text, modifier scope, or list introductions | references/technical-style.md |
Files (skills)
-
references
-
adr-template.md 2.4 KB
Loading… -
api-docs-guide.md 883 B
Loading… -
design-doc-template.md 3.5 KB
Loading… -
how-to-guide.md 864 B
Loading… -
readme-guide.md 855 B
Loading… -
rfc-template.md 3.6 KB
Loading… -
technical-style.md 4.7 KB
Loading…
-
-
SKILL.md 3.9 KB
--- name: docs description: "Write or revise technical documentation around one reader job: reference, operation, review, decision, or product alignment. Use for READMEs, API docs, operational how-tos, RFCs, product design docs, architecture proposals, and ADRs." --- # Technical Documentation Writer Write for the reader's job: what they came to understand, decide, or do. A technically correct doc that does not serve that job is still a failed doc. ## Boundaries - Use `blog` for publishable articles with an argument, story, or public-facing lesson. - The user-invoked `teach` skill owns persistent learning workspaces and HTML lessons. - Use this skill for reference docs, team proposals, decision records, READMEs, API docs, and how-to docs whose primary purpose is work, review, or operation. ## Workflow ### 1. Name the doc type and reader job Identify the document type before drafting: README, API docs, how-to, RFC or architecture proposal, product design doc, or ADR. Complete when: - the doc type is named - the primary audience is named - the reader job is stated as `Reader needs to <do/decide/understand> so they can <outcome>` - missing inputs are requested before drafting ### 2. Load the matching reference Use the routing table below. Load every reference whose condition applies before writing. The technical-style reference is additive: load it only when the prose needs sentence-level clarity work, not merely because the document is technical. Complete when every applicable reference has been loaded, or no reference applies and that is stated. ### 3. Gather the minimum context Ask only for context needed by the reader job: - current state and desired outcome - constraints, dependencies, and owners - concrete examples, commands, APIs, or decisions - known errors, risks, alternatives, or non-goals Complete when every required placeholder in the selected template has either source material or an explicit `TBD`/question for the user. ### 4. Draft for use, review, or decision Lead with what the reader needs first. Show before explaining when the reader must do something; state the decision or proposal before deep rationale when the reader must decide. Complete when: - the opening answers the reader job - every section exists to help the reader do, decide, or understand something - examples are realistic and include required setup/config/error handling when relevant - uncertainties are marked instead of invented ### 5. Run the quality gate Before delivering, verify: - [ ] First sentence says what this is or what decision/proposal is being made - [ ] Code examples or commands were run when an environment is available; otherwise marked unverified - [ ] Required config, inputs, env vars, and permissions are documented - [ ] Common errors or risks include what to do next - [ ] Links referenced in the doc were checked when accessible - [ ] Terminology is consistent: one name per concept - [ ] No "simple" / "just" / "easy" for user actions Complete when all applicable checks pass or failures are called out explicitly. ## References | Priority | Load when | Reference | | --- | --- | --- | | 1 | Decision already made; capture context, decision, and consequences | `references/adr-template.md` | | 1 | Change not decided; solicit review, including system design with migration concerns | `references/rfc-template.md` | | 1 | Scoping new product work with goals, non-goals, user stories, and metrics | `references/design-doc-template.md` | | 2 | Creating or revising a README | `references/readme-guide.md` | | 2 | Creating or revising API documentation | `references/api-docs-guide.md` | | 2 | Creating or revising a task-oriented how-to guide | `references/how-to-guide.md` | | 3 | Technical prose needs sentence-level clarity work: reader-mode boundaries, condition/action order, common-path ordering, technical names, link text, modifier scope, or list introductions | `references/technical-style.md` |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.