Simplify docs

Skill MAHDTech/agent-skills/skills/writing/simplify-docs

Make AI Agents great again!

Install

npx -y skills add MAHDTech/agent-skills --skill simplify-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Simplify documentation for clarity and readability with approval-gated edits. Use when asked to simplify, rewrite, restructure, or de-clutter a doc — README, setup guide, reference or technical documentation — so it scans faster and leads with the shortest successful path.

SKILL.md

3.0 KB, as published. Nobody here has run it

Simple Docs for Humans and Agents

Use this command to write or rewrite documentation so it is simple, fast to scan, and easy to execute.

Primary Goal

Bias toward simple docs.
Start with the shortest successful path.
Preserve original meaning and factual content while reordering for clarity.

Required Output Order

Quickstart (always first)
Main workflow
Configuration/reference lists (when relevant)
Alternative paths (only when they are true user/code path alternatives)
Extra details at the end inside <details><summary>...</summary>...</details>

Approval Gate (Required)

Before editing any file, show a change preview for approval.
Use this exact preview structure for each file:
- Additions
- Removals
- Changes
Show the concrete text to be added, removed, or changed.
Wait for explicit user approval before applying edits.
Apply only the approved edits.
If approval is not granted, do not modify files.

Core Rules

Optimize for both human readers and agent readers.
Maximize copy-paste command snippets.
Prefer short sections and concise language.
Use lists for structured information.
Use Mermaid diagrams when they improve understanding of flow or architecture.
Avoid unnecessary sections.
Avoid "Optional" sections unless they represent an actual alternate path.
Put superfluous/background material at the end.
Add "Code Structure" only when repository layout helps task completion.

Command Block Rules (Strict)

Do not place comments inside bash code blocks.
Put labels outside code blocks.

Correct pattern:

Start the server:

make start_server

Run database migrations:

make migrate_db

Incorrect pattern (separate steps combined in one unlabeled block):

make start_server
make migrate_db

Section Defaults

Use only sections that add value for the specific document. Default section set:

Quickstart
Main Workflow
Configuration
Code Structure (only if useful)
Troubleshooting (only for real recurring issues)

Configuration List Format

If environment variables or configuration values are required, use this format:

APP_ENV: Runtime environment (Default: development)
API_URL: Base URL for API calls (Default: http://localhost:8000)

Details Block Rule

Move long explanations, implementation notes, and low-priority reference material into details blocks:

<details>
<summary>Deep dive: request lifecycle</summary>

Detailed explanation here.

</details>

Deliverable

Return the final output as Markdown (.md).
Keep all important content, but simplify, reorder, and prioritize for quick execution.