Cognitive-Load-Friendly Doc Design
Write docs that reduce cognitive load for readers and reviewers, making them quick to scan, retain, and verify.
The skill only suggests running read-only git diff and gh pr view commands, does not authorize write operations or system state changes, and behaves within least privilege. However, it lacks explicit user confirmation or scope limitation, and does not explain handling of sensitive data. It depends on external commands git and gh without dependency security notes. Source attribution is clear (author, license), but source trustworthiness is unverified. Deductions: missing user confirmation and sensitive data handling, external command dependencies without security declarations.
The skill instructions are clear and internally consistent, providing a clear framework and commands. However, it lacks tests, edge cases, and error handling notes. On command failure, no diagnostic advice is provided, requiring the user to troubleshoot. Static review cannot execute verification, and the skill itself provides no reproducible test evidence. Deductions: no test coverage, insufficient failure feedback, unclear environment dependencies.
The skill's applicable scenarios are clearly defined (writing guides, READMEs, RFCs, onboarding docs, etc.), but non-fit boundaries are not well-defined, and trigger conditions rely only on description without precise semantic keywords. The skill content is entirely in English without Chinese support, but the skill itself does not rely on network services and is accessible from mainland-China networks. Deductions: unclear non-fit boundaries, insufficient Chinese support.
The skill has clear name, description, version, and author information, but the license (Apache-2.0) is inconsistent with the repository root MIT license. Lacks changelog, known limitations, and maintenance responsibility notes. No examples or FAQ, incomplete install/dependency notes. Deductions: license inconsistency, missing changelog and known limitations.
The skill provides clear documentation structure and specific commands, likely achieving the core task (reducing cognitive load), but lacks actual output examples or verification evidence. Value proposition is not quantified, and marginal benefit over manual or alternative methods is unclear. Static review cannot verify output direct usability. Deductions: lack of representative output verification and comparative evidence.
Key claims (e.g., reducing cognitive load) lack traceable evidence, and no reproducible tests are provided. The repository has CI workflows and tests, but they do not cover the skill's key paths. Deductions: claims without evidence, tests not covering skill paths.
- The skill depends on git and gh commands, which may not exist or have incompatible versions; users should ensure they are installed.
- The skill's license is inconsistent with the repository root (Apache-2.0 vs MIT), potentially causing confusion.
- The skill does not provide user confirmation or scope limitation; use with caution.
- The skill content is in English; Chinese users may need additional translation.
What does this skill do, and when should you use it?
This skill provides a set of documentation patterns and a default structure to help authors lead with the answer, use progressive disclosure, chunk information, and employ signposting, so readers can quickly understand and retain content. It emphasizes review empathy by designing docs that let reviewers verify intent without reconstructing the whole story. The skill includes practical commands to inspect markdown changes and PR line counts to gauge cognitive load. It is part of the Gentle-AI repository, which is MIT-licensed, while the skill itself declares Apache-2.0.
Provides six critical patterns (lead with answer, progressive disclosure, chunking, signposting, recognition over recall, review empathy). Offers a default documentation structure template (title, one-paragraph summary, quick path, details table, checklist, next step). Gives specific guidance for PR and review docs. Includes git command to list changed markdown files and gh command to view PR additions/deletions/changedFiles.
- A developer writing a PR description wants reviewers to quickly grasp the core change and reduce back-and-forth.
- A maintainer drafting contributor or maintainer guides wants newcomers to get up to speed quickly.
- A technical writer creating architecture or workflow docs that need to be scannable and long-lasting.
- During code review, a reviewer needs clear structure and checklists to confirm changes meet expectations.
- A team member writing an RFC wants readers from different backgrounds to understand easily.
What are this skill's strengths and limitations?
- Provides clear, actionable patterns that are easy to follow.
- Offers a default doc template that can be reused directly.
- Specifically targets reviewer burnout, improving review efficiency.
- Includes practical commands to estimate cognitive load of changes.
- Platform-agnostic, highly portable.
- Example commands depend on external tools (git and gh) with no installation or alternative provided.
- No automated tests or validation; effectiveness relies on author discipline.
- May conflict with repositories that already have stronger templates; requires adaptation.
- Lacks specific thresholds for what counts as 'long' or 'dense' docs.
How do you install this skill?
This skill resides at internal/assets/skills/cognitive-doc-design/SKILL.md in the Gentle-AI repository. As part of the collection, install it using the Gentle-AI installer (curl script on macOS/Linux or PowerShell on Windows). Alternatively, manually place the folder into your agent's skills directory that supports Agent Skills.
How do you use this skill?
Prompt your agent to use the cognitive doc design skill when writing or editing documentation. The skill provides patterns and structure suggestions. If using Git and GitHub CLI, run git diff --name-only -- '*.md' to see changed markdown files, or gh pr view <PR_NUMBER> --json additions,deletions,changedFiles to inspect PR line counts.