Skip to content
Get packs

Guide · Agent skill

How to use the Cognitive Doc Design agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The cognitive-doc-design skill is an agent skill that changes how your AI agent writes documentation. Once installed, it follows habits meant to reduce the mental effort readers need, such as putting the answer first and using tables and checklists instead of long paragraphs. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs to run.

Cognitive Doc DesignGentleman-Programming/gentle-ai · MIT

Quick start

  1. 1Download the ZIP. Get the cognitive-doc-design ZIP from the item page. It contains SKILL.md.
  2. 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
  3. 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
  4. 4Ask for a documentation task. Describe the document, its audience and the reader's goal in plain language.
  5. 5Review the output. Check that the answer comes first, sections are short, and any checklist matches the real work.
  6. 6Optionally inspect PR size. Run the gh pr view command with your PR number to see added, deleted and changed file counts.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This skill is described as designing docs that reduce cognitive load. Its trigger covers writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.

When the skill is loaded, the agent applies six documentation patterns: lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, and review empathy. It also suggests a default document shape unless the repository already has a stronger template.

  • Puts the decision, action, or outcome first, with context after.
  • Starts with the happy path and adds details and edge cases later.
  • Keeps related information in small sections and flat lists short.
  • Prefers tables, checklists, examples and templates over prose the reader must remember.
  • For PR descriptions, states what to review first and what is out of scope, and links chained PRs.

Install the cognitive-doc-design skill

The skill ships as a single file, SKILL.md. Download the ZIP from the item page and unzip it into one of two locations depending on how you want to use it.

For a personal setup available across projects, unzip into your user skills folder. For a single project, unzip into that project's .claude/skills/ folder so it travels with the repository. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your repository
  • Claude apps: Settings → Capabilities → Skills, then upload the skill

Trigger the skill with natural requests

You do not need a special command. Ask for documentation work in ordinary language, and the agent can load the skill when the request matches its trigger. Mention the kind of document and the audience so the agent knows which patterns matter.

The skill is most useful for PR descriptions, contributor or maintainer guides, architecture or onboarding docs, and any existing doc that feels long or hard to scan.

  • "Write a README for this library that a new contributor can follow in five minutes."
  • "Draft a PR description so reviewers know what to check first."
  • "Rewrite this architecture doc so it is easier to scan."
  • "Create an onboarding guide for the payments service."

Use the optional PR and git commands

The skill includes two shell commands in its instructions. The first lists markdown files changed on the current branch. The second checks how large a pull request is, which helps you decide whether a PR needs splitting before review. The PR command uses the GitHub CLI, so you need gh installed and authenticated.

Both commands are optional. The agent can use them when you ask it to inspect changes, but you can also run them yourself.

  • git diff --name-only -- '*.md' lists changed markdown files on the current branch.
  • gh pr view <PR_NUMBER> --json additions,deletions,changedFiles shows the PR's added and deleted lines and changed file count.
git diff --name-only -- '*.md' gh pr view <PR_NUMBER> --json additions,deletions,changedFiles

Requirements and safety notes

The skill requires git for the changed-markdown command and the GitHub CLI (gh) for the optional PR-size command. It does not run scripts and does not use the network, according to its listing. Its only files are SKILL.md.

Because the skill is instructions only, its effect is on the text the agent writes. Review generated docs as you would any change, especially when the repository has its own templates.

  • Runs scripts: no
  • Uses network: no
  • Licence: MIT

Tips for getting better docs

Tell the agent the audience and the reader's task, such as a new contributor setting up the project or a reviewer checking one decision. The patterns depend on knowing who the document is for.

If your project already has a documentation template, the skill's default shape should defer to it, but only if the agent notices that template. Point the agent to the template file explicitly to avoid conflicts.

  • Name the audience and the job the reader needs to finish.
  • Point to your existing template when you have one.
  • Ask for a checklist of acceptance criteria in PR descriptions.
  • Split large PRs when the changed-line count is high.

What people use it for

  • Writing a README with a quick path for installing and running the project.
  • Drafting a PR description that tells reviewers what to check first and what is out of scope.
  • Structuring an architecture or onboarding doc with tables and checklists.
  • Turning a long, dense contributor guide into short, scannable sections.

Frequently asked questions

Is the cognitive-doc-design skill free?

The skill is listed under the MIT licence. The item page does not list a price, so check the repository for the current licence terms before relying on it.

What do I need to use cognitive-doc-design?

You need an agent that supports skills, such as the Claude apps or Claude Code. The optional PR command requires the GitHub CLI (gh), and the changed-files command requires git.

Where do I put the skill folder?

Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Does the skill run scripts or access the internet?

According to its listing, it runs no scripts and uses no network. It consists of a single SKILL.md file with instructions.

Will it override my project's documentation template?

Not reliably. The default shape only defers to an existing template if the agent notices it, so point the agent to your template in the request.

Is it suitable for marketing or creative writing?

No. It targets technical, review-facing documentation, and a structured checklist style would be wrong for creative or marketing copy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you write READMEs, contributor or architecture guides, onboarding docs, or PR descriptions that reviewers must check quickly, especially across a repo that wants consistent structure. Pick something else for creative or marketing copy, or if your project has a strict template you cannot have the agent override.

Download the skill