documenting-code

Name: documenting-code
Author: alexei-led

6installs5forks

How to install documenting-code?

alexei-led/cc-thingz/documenting-code

$npx -y skills add alexei-led/cc-thingz --skill documenting-code

Installs into the current project.

Summary

Scope: documentation files, agent instruction files, and useful code comments only. Not for code-quality review; use reviewing-code for that.

Files · 1

View on GitHub

SKILL.md

1	# Documenting Code
2
3	Scope: documentation files, agent instruction files, and useful code comments
4	only. Not for code-quality review; use `reviewing-code` for that.
5
6	Update docs from implementation facts. Identify the reader first. Apply edits
7	only when write tools are available. If evidence or validation is missing, report
8	the gap instead of claiming docs are current.
9
10	## Tool use
11
12	- Use Read for implementation, tests, and existing docs.
13	- Use Edit for targeted doc changes. Use Write only for new docs or full rewrites.
14	- Use Bash only for status, diffs, markdown lint, docs checks, and narrow repo validation.
15	- Use TaskCreate only for a large documentation audit that needs a bounded read-only mapping pass. Verify the returned claims before editing.
16	- Use AskUserQuestion only when scope or reader is ambiguous.
17
18	## Reader model
19
20	Human reader:
21
22	- Short, structured, readable, and useful.
23	- Start with what the reader can do after reading.
24	- Use examples close to the concept.
25	- Use Mermaid diagrams only for non-trivial structure, flow, lifecycle,
26	ownership, or trade-offs.
27	- Match existing docs style; do not invent custom fonts, colors, or visual design.
28
29	Agent reader:
30
31	- Concise operational instructions for LLMs.
32	- Use headers, bullets, numbered steps, and exact output contracts.
33	- Remove fluff, duplicate rules, generic knowledge, tables, diagrams, and visual polish.
34	- Route scoring or quality review of instructions to `reviewing-instructions`.
35
36	Code reader:
37
38	- Comments/docstrings explain contracts, constraints, invariants, side effects,
39	errors, or non-obvious choices.
40	- Delete comments that restate code.
41	- Avoid comments in tests unless they explain an essential external behavior or edge case.
42
43	## Workflow
44
45	1. Determine scope from the user request or changed files. Do not ask if clear.
46	2. Read relevant code, tests, and existing docs.
47	3. Choose reader type: human, agent, code, or mixed.
48	4. Compare docs to current behavior. Code wins unless the user says docs are the contract.
49	5. Update the smallest useful docs.
50	6. Verify docs and runnable examples when practical.
51	7. Report changed files, checks, and remaining issues.
52
53	For large audits only, spawn one bounded read-only subagent with a narrow brief:
54	map changed behavior, existing docs, stale sections, and missing docs. Require
55	file paths and line evidence. Do not let the subagent edit.
56
57	## What to update
58
59	- README usage, setup, quick start, and release notes for user-visible changes.
60	- API docs for parameter, output, error, side effect, or example changes.
61	- Architecture docs for boundary, data-flow, ownership, deployment, or major trade-off changes.
62	- Agent docs for skills, agents, hooks, commands, tools, routing, and operating rules.
63	- Generated catalogs only through source files and generator scripts.
64	- Code comments only when they add useful contract or reasoning value.
65
66	## Verification
67
68	Prefer the narrowest relevant checks:
69
70	```bash
71	git diff --stat
72	markdownlint-cli2 '*/.md'
73	make lint-markdown
74	make validate
75	```
76
77	Run documented commands or examples when practical. If a check cannot run, state why.
78
79	## Output
80
81	```markdown
82	## Documentation Update
83
84	Updated:
85
86	- `path` — <what changed and reader served>
87
88	Verified:
89
90	- <check>: passed \| skipped (<reason>)
91
92	Issues: none \| <remaining issue>
93	```
94
95	## Reviewer output
96
97	Read-only role only. Apply nothing and run nothing.
98
99	```markdown
100	## Proposed Changes
101
102	### Change 1: <brief description>
103
104	File: `path/to/doc`
105	Action: CREATE \| MODIFY \| DELETE
106	Reader: human \| agent \| code
107
108	Code:
109	<doc content or patch-sized replacement with enough context>
110
111	Rationale: <code fact that makes this stale or missing>
112	```
113
114	## Failure handling
115
116	- Ambiguous scope: ask one scoped question.
117	- No recent changes: ask what to document instead of inventing docs.
118	- Generated doc target: edit source and rebuild, not generated output.
119	- Docs/code conflict: report it; update docs to code unless user says docs are intended contract.
120	- Verification failure: quote the exact failure and do not claim success.

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

documenting-code

6installs5forks

View on GitHub

How to install documenting-code?

alexei-led/cc-thingz/documenting-code

$npx -y skills add alexei-led/cc-thingz --skill documenting-code

Installs into the current project.

Summary

Scope: documentation files, agent instruction files, and useful code comments only. Not for code-quality review; use reviewing-code for that.

Files · 1

View on GitHub

SKILL.md

1	# Documenting Code
2
3	Scope: documentation files, agent instruction files, and useful code comments
4	only. Not for code-quality review; use `reviewing-code` for that.
5
6	Update docs from implementation facts. Identify the reader first. Apply edits
7	only when write tools are available. If evidence or validation is missing, report
8	the gap instead of claiming docs are current.
9
10	## Tool use
11
12	- Use Read for implementation, tests, and existing docs.
13	- Use Edit for targeted doc changes. Use Write only for new docs or full rewrites.
14	- Use Bash only for status, diffs, markdown lint, docs checks, and narrow repo validation.
15	- Use TaskCreate only for a large documentation audit that needs a bounded read-only mapping pass. Verify the returned claims before editing.
16	- Use AskUserQuestion only when scope or reader is ambiguous.
17
18	## Reader model
19
20	Human reader:
21
22	- Short, structured, readable, and useful.
23	- Start with what the reader can do after reading.
24	- Use examples close to the concept.
25	- Use Mermaid diagrams only for non-trivial structure, flow, lifecycle,
26	ownership, or trade-offs.
27	- Match existing docs style; do not invent custom fonts, colors, or visual design.
28
29	Agent reader:
30
31	- Concise operational instructions for LLMs.
32	- Use headers, bullets, numbered steps, and exact output contracts.
33	- Remove fluff, duplicate rules, generic knowledge, tables, diagrams, and visual polish.
34	- Route scoring or quality review of instructions to `reviewing-instructions`.
35
36	Code reader:
37
38	- Comments/docstrings explain contracts, constraints, invariants, side effects,
39	errors, or non-obvious choices.
40	- Delete comments that restate code.
41	- Avoid comments in tests unless they explain an essential external behavior or edge case.
42
43	## Workflow
44
45	1. Determine scope from the user request or changed files. Do not ask if clear.
46	2. Read relevant code, tests, and existing docs.
47	3. Choose reader type: human, agent, code, or mixed.
48	4. Compare docs to current behavior. Code wins unless the user says docs are the contract.
49	5. Update the smallest useful docs.
50	6. Verify docs and runnable examples when practical.
51	7. Report changed files, checks, and remaining issues.
52
53	For large audits only, spawn one bounded read-only subagent with a narrow brief:
54	map changed behavior, existing docs, stale sections, and missing docs. Require
55	file paths and line evidence. Do not let the subagent edit.
56
57	## What to update
58
59	- README usage, setup, quick start, and release notes for user-visible changes.
60	- API docs for parameter, output, error, side effect, or example changes.
61	- Architecture docs for boundary, data-flow, ownership, deployment, or major trade-off changes.
62	- Agent docs for skills, agents, hooks, commands, tools, routing, and operating rules.
63	- Generated catalogs only through source files and generator scripts.
64	- Code comments only when they add useful contract or reasoning value.
65
66	## Verification
67
68	Prefer the narrowest relevant checks:
69
70	```bash
71	git diff --stat
72	markdownlint-cli2 '*/.md'
73	make lint-markdown
74	make validate
75	```
76
77	Run documented commands or examples when practical. If a check cannot run, state why.
78
79	## Output
80
81	```markdown
82	## Documentation Update
83
84	Updated:
85
86	- `path` — <what changed and reader served>
87
88	Verified:
89
90	- <check>: passed \| skipped (<reason>)
91
92	Issues: none \| <remaining issue>
93	```
94
95	## Reviewer output
96
97	Read-only role only. Apply nothing and run nothing.
98
99	```markdown
100	## Proposed Changes
101
102	### Change 1: <brief description>
103
104	File: `path/to/doc`
105	Action: CREATE \| MODIFY \| DELETE
106	Reader: human \| agent \| code
107
108	Code:
109	<doc content or patch-sized replacement with enough context>
110
111	Rationale: <code fact that makes this stale or missing>
112	```
113
114	## Failure handling
115
116	- Ambiguous scope: ask one scoped question.
117	- No recent changes: ask what to document instead of inventing docs.
118	- Generated doc target: edit source and rebuild, not generated output.
119	- Docs/code conflict: report it; update docs to code unless user says docs are intended contract.
120	- Verification failure: quote the exact failure and do not claim success.

People who liked this also viewed

6 picks

Type