cognitive-doc-design
Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.
- Installs
- 70
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/gentleman-programming/gentle-ai --skill cognitive-doc-design- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads cognitive-doc-design automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
When to Use
Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
Use it especially for:
- PR descriptions and review notes.
- Contributor or maintainer guides.
- Architecture, workflow, or onboarding docs.
- Any doc that currently feels long, dense, or hard to scan.
Critical Patterns
| Pattern | Rule |
|---|---|
| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
| Chunking | Group related information into small sections. Keep flat lists short. |
| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
Documentation Shape
Use this default structure unless the repo already provides a stronger template:
# <Outcome-oriented title>
<One paragraph: what changed, who it helps, and why it matters.>
## Quick path
1. <First action>
2. <Second action>
3. <Verification or expected result>
## Details
| Topic | Decision |
|-------|----------|
| <area> | <concise explanation> |
## Checklist
- [ ] <Reader can confirm this>
- [ ] <Reader can confirm that>
## Next step
<Link or action that continues the workflow.>
PR and Review Docs
When documenting a PR, reduce reviewer burnout by making the review path explicit:
- State what to review first.
- State what is intentionally out of scope.
- Link the previous and next PR when work is chained.
- Keep each section focused on one decision or unit of work.
- Use checklists for acceptance criteria and verification.
Commands
# Check markdown files changed in the current branch
git diff --name-only -- '*.md'
# Inspect PR changed-line count for cognitive load
gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
FAQ
What does the cognitive-doc-design skill do?
Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.
How do I install cognitive-doc-design?
Run npx skills add https://github.com/gentleman-programming/gentle-ai --skill cognitive-doc-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cognitive-doc-design/ (personal) or .claude/skills/cognitive-doc-design/ (project).
Which AI agents can use cognitive-doc-design?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is cognitive-doc-design safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains cognitive-doc-design?
It is published by gentleman-programming in gentleman-programming/gentle-ai. It has 70 recorded installs.
More from gentleman-programming/gentle-ai
comment-writer
gentleman-programming/gentle-ai
Write warm, direct collaboration comments. Trigger: PR feedback, issue replies, reviews, Slack messages, or GitHub comments.
gentle-ai-branch-pr
gentleman-programming/gentle-ai
Create Gentle AI pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review.
gentle-ai-chained-pr
gentleman-programming/gentle-ai
Trigger: PRs over 400 lines, stacked PRs, review slices. Split oversized changes into chained PRs that protect review focus.
work-unit-commits
gentleman-programming/gentle-ai
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.