Apache-2.0Engineering Docs

Cognitive Doc Design

Name: Cognitive Doc Design
Author: Gentleman-Programming

By Gentleman-Programming· Gentleman-Programming/gentle-shell· 0

Design documentation that's easy to understand, remember, and scan quickly.

Installation

1
Make sure Claude is on your device and in your terminal.
Skills load from ~/.claude/skills/ when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then run claude in any terminal to verify.
One-time setup
```
npm i -g @anthropic-ai/claude-code
```
Already have it? Skip ahead.

Paste into Claude Code or into your terminal.

Install

git clone ht••••••••••••••••••••••••••••••••••••••••••••••••••••••• •••••••••••••••••••••••••••••••••••••••• •• ••••• •• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •• •• •• •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

This copies the whole skill folder into ~/.claude/skills/gentle-ai-cognitive-doc-design-gentleman-programming/ — the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Safe default: works for every skill.

Faster alternative (instruction-only skills)

Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.

Quick install (SKILL.md only)

mkdir -p ~/.•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •• •••• ••••• •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from ~/.claude/skills/). New skills are picked up on startup.
Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.

Prefer to read the source first? Open on GitHub.

When Claude uses it

Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.

What this skill does

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

Related skills

Word Document Editor

anthropics

Create, edit, and format Word documents with tables, images, and tracked changes.

OfficialProprietary. LICENSE.txt has complete terms

Ask Questions If Underspecified

trailofbits

Ask clarifying questions before starting work on ambiguous requests.

CLAUDE.md Optimizer

daymade

Optimize your CLAUDE.md file for clarity, efficiency, and maintainability.

Claude Skills Troubleshooter

daymade

Diagnose and fix plugin installation, enablement, and activation problems.