# Simplify Docs

> 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: `mahdtech/simplify-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mahdtech/simplify-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mahdtech/simplify-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: MAHDTech (https://skillmd.com/u/mahdtech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mahdtech/simplify-docs

---


# 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

1. Quickstart (always first)
2. Main workflow
3. Configuration/reference lists (when relevant)
4. Alternative paths (only when they are true user/code path alternatives)
5. 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:

```bash
make start_server
```

Run database migrations:

```bash
make migrate_db
```

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

```bash
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:

```markdown
<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.