documentation

Name: documentation
Author: DevelopersGlobal

64stars10forks

How to install documentation?

developersglobal/ai-agent-skills/documentation

$npx -y skills add DevelopersGlobal/ai-agent-skills --skill documentation

Installs into the current project.

Summary

Document decisions, not just implementations. ADRs for architectural choices, inline docs for non-obvious code, and runbooks for operational knowledge.

Files · 1

View on GitHub

SKILL.md

1	## Overview
2
3	Code explains what. Documentation explains why. The most valuable documentation records decisions that aren't obvious from reading the code: why this architecture, why this tradeoff, why not the obvious alternative.
4
5	## When to Use
6
7	- After any significant architectural decision
8	- Before complex code that future maintainers will question
9	- When an operational procedure isn't self-evident
10	- When a non-obvious tradeoff was made
11
12	## Process
13
14	### Step 1: Architectural Decision Records (ADRs)
15
16	For every significant architectural decision:
17	1. Write an ADR with:
18	- Context: What was the situation requiring a decision?
19	- Decision: What was decided?
20	- Alternatives considered: What else was evaluated and why rejected?
21	- Consequences: What are the positive and negative consequences?
22	- Status: Proposed \| Accepted \| Deprecated \| Superseded
23	2. Store ADRs in `docs/decisions/` as numbered markdown files.
24
25	Verify: Every significant decision in the last sprint has an ADR.
26
27	### Step 2: Code-Level Documentation
28
29	3. Document the WHY, not the WHAT:
30	- ✅ `// Using exponential backoff here — the payment API has strict rate limits (3 req/sec)`
31	- ❌ `// Retry the request`
32	4. Document non-obvious algorithmic choices.
33	5. Document external constraints (rate limits, API quirks, platform limitations).
34	6. Remove comments that state the obvious — they add noise.
35
36	Verify: Every non-obvious code block has a "why" comment.
37
38	### Step 3: Runbooks
39
40	7. For every production process that humans execute, write a runbook:
41	- When is this runbook used?
42	- What steps to execute?
43	- What does "done" look like?
44	- What could go wrong and how to recover?
45	8. Runbooks live in `docs/runbooks/`.
46
47	Verify: Every on-call alert has a linked runbook.
48
49	### Step 4: README Currency
50
51	9. README reflects current state (not v1 state).
52	10. Setup instructions work on a fresh machine.
53	11. Architecture diagram updated after significant changes.
54
55	## Common Rationalizations (and Rebuttals)
56
57	\| Excuse \| Rebuttal \|
58	\|--------\|----------\|
59	\| "The code is self-documenting" \| Code says what; documentation says why. Both are needed. \|
60	\| "I'll document it later" \| The context in your head right now is irreplaceable. Write it now. \|
61	\| "Docs go stale" \| Outdated docs are better than no docs. Update when you touch the code. \|
62
63	## Verification
64
65	- [ ] ADRs written for significant architectural decisions
66	- [ ] Non-obvious code blocks have "why" comments
67	- [ ] Every production alert has a linked runbook
68	- [ ] README is current and setup instructions work
69
70	## References
71
72	- [git-workflow skill](../git-workflow/SKILL.md)
73	- [Michael Nygard's ADR template](https://github.com/joelparkerhenderson/architecture-decision-record)

People who liked this also viewed

6 picks

Type

grill-with-docsA relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.SkillsJul 2026537k182k
lark-minutes飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词、申请妙记查看/编辑权限。当给出minute_token、本地音视频文件，要查/改/转妙记产物，或用户明确要主动申请妙记权限时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要SkillsJul 2026379k16k
lark-markdown飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。SkillsJul 2026295k16k
docxUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', SkillsJul 2026157k163k
edit-articleSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026154k181k
lark-note飞书会议纪要（Note）直查：已知 note_id 时查询纪要详情、展示类型、关联文档 token，并读取 unified 原始逐字记录。当用户已持有 note_id，或从文档显式 vc-node-id 获得 note_id 时使用。不负责会议/日程/妙记定位、文档标题搜索或 Docx 正文读取。SkillsJul 2026154k16k

documentation

64stars10forks

View on GitHub

How to install documentation?

developersglobal/ai-agent-skills/documentation

$npx -y skills add DevelopersGlobal/ai-agent-skills --skill documentation

Installs into the current project.

Summary

Document decisions, not just implementations. ADRs for architectural choices, inline docs for non-obvious code, and runbooks for operational knowledge.

Files · 1

View on GitHub

SKILL.md

1	## Overview
2
3	Code explains what. Documentation explains why. The most valuable documentation records decisions that aren't obvious from reading the code: why this architecture, why this tradeoff, why not the obvious alternative.
4
5	## When to Use
6
7	- After any significant architectural decision
8	- Before complex code that future maintainers will question
9	- When an operational procedure isn't self-evident
10	- When a non-obvious tradeoff was made
11
12	## Process
13
14	### Step 1: Architectural Decision Records (ADRs)
15
16	For every significant architectural decision:
17	1. Write an ADR with:
18	- Context: What was the situation requiring a decision?
19	- Decision: What was decided?
20	- Alternatives considered: What else was evaluated and why rejected?
21	- Consequences: What are the positive and negative consequences?
22	- Status: Proposed \| Accepted \| Deprecated \| Superseded
23	2. Store ADRs in `docs/decisions/` as numbered markdown files.
24
25	Verify: Every significant decision in the last sprint has an ADR.
26
27	### Step 2: Code-Level Documentation
28
29	3. Document the WHY, not the WHAT:
30	- ✅ `// Using exponential backoff here — the payment API has strict rate limits (3 req/sec)`
31	- ❌ `// Retry the request`
32	4. Document non-obvious algorithmic choices.
33	5. Document external constraints (rate limits, API quirks, platform limitations).
34	6. Remove comments that state the obvious — they add noise.
35
36	Verify: Every non-obvious code block has a "why" comment.
37
38	### Step 3: Runbooks
39
40	7. For every production process that humans execute, write a runbook:
41	- When is this runbook used?
42	- What steps to execute?
43	- What does "done" look like?
44	- What could go wrong and how to recover?
45	8. Runbooks live in `docs/runbooks/`.
46
47	Verify: Every on-call alert has a linked runbook.
48
49	### Step 4: README Currency
50
51	9. README reflects current state (not v1 state).
52	10. Setup instructions work on a fresh machine.
53	11. Architecture diagram updated after significant changes.
54
55	## Common Rationalizations (and Rebuttals)
56
57	\| Excuse \| Rebuttal \|
58	\|--------\|----------\|
59	\| "The code is self-documenting" \| Code says what; documentation says why. Both are needed. \|
60	\| "I'll document it later" \| The context in your head right now is irreplaceable. Write it now. \|
61	\| "Docs go stale" \| Outdated docs are better than no docs. Update when you touch the code. \|
62
63	## Verification
64
65	- [ ] ADRs written for significant architectural decisions
66	- [ ] Non-obvious code blocks have "why" comments
67	- [ ] Every production alert has a linked runbook
68	- [ ] README is current and setup instructions work
69
70	## References
71
72	- [git-workflow skill](../git-workflow/SKILL.md)
73	- [Michael Nygard's ADR template](https://github.com/joelparkerhenderson/architecture-decision-record)

People who liked this also viewed

6 picks

Type