agentsclimarketplace

Cmd docs idiot proof

Skill Olshansk/agent-skills/skills/cmd-docs-idiot-proof

Simplify documentation for clarity and scannability with approval-gated editsFrom its SKILL.md

Install
npx -y skills add Olshansk/agent-skills --skill cmd-docs-idiot-proof

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

  • 9 stars9 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.

SKILL.md

2.8 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

  1. Quickstart (always first)
  2. Main workflow
  3. Configuration/reference tables (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 Markdown tables when information is structured.
  • 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 a command:

make run_command

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

make start_server
make run_command

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 Table Format

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

NamePurposeDefault
APP_ENVRuntime environmentdevelopment
API_URLBase URL for API callshttp://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.

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.