playbooks

home / skills / michalvavra / agents / write-docs

write-docs skill

/skills/write-docs

This skill creates AI-scannable documentation templates that are concise, consistent, and ready to reuse across projects.

npx playbooks add skill michalvavra/agents --skill write-docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
923 B
---
name: write-docs
description: Write AI-scannable technical documentation.
---

# Write Documentation

Documentation that is scannable, consistent, and actionable for AI agents.

## Structure

- Max 150 lines per file, one concept per file
- Start with `description:` in YAML frontmatter
- Add TL;DR section at top with most-needed info

## Content

- No duplicates (define once, link elsewhere)
- Use tables for structured data (parameters, config)
- Concrete examples for everything (copy-pasteable)
- Link to real code as templates

## Naming

| Pattern | Use For | Example |
|---------|---------|---------|
| `README.md` | Directory overview | `docs/README.md` |
| `{noun}.md` | Reference | `entities.md` |
| `{verb}-{noun}.md` | How-to | `add-entity.md` |

## Tips

- Use consistent terms (one term per concept)
- Group by task ("How to add X") not system ("X overview")
- Include troubleshooting for common errors

Overview

This skill generates AI-scannable technical documentation that is scannable, consistent, and directly usable by coding agents. It enforces short files, one concept per file, and clear frontmatter with a TL;DR so agents can find the most important information quickly.

How this skill works

The skill inspects project docs and produces files following a strict structure: YAML frontmatter beginning with description:, a top-level TL;DR, and concrete examples. It splits content into single-concept files under 150 lines, eliminates duplicates by defining each concept once and linking to it, and formats tables for structured data such as parameters and configs.

When to use it

  • Preparing documentation for automated tools or code-generation agents
  • Converting long monolithic docs into short, focused files
  • Onboarding new contributors who rely on copy-pasteable examples
  • Creating reference and how-to pages that need fast scanning
  • Standardizing docs across a multi-repo project

Best practices

  • Limit files to ~150 lines and cover only one concept per file
  • Start each file with YAML frontmatter containing description:
  • Include a TL;DR at the top with the single-most-critical info
  • Use tables for parameters and config for predictable parsing
  • Provide concrete, copy-pasteable examples and link to real code templates
  • Avoid duplicate definitions; define once and link everywhere

Example use cases

  • Split a large API guide into per-endpoint reference files with examples and param tables
  • Create how-to guides like add-entity.md that show step-by-step commands and expected outputs
  • Produce configuration reference files that list keys, types, defaults, and valid values in tables
  • Generate README.md for each docs directory that links to the one-concept files
  • Add troubleshooting sections in each file for common errors and quick fixes

FAQ

What belongs in the TL;DR?

A one- or two-line summary that states the goal, the core command or snippet, and the expected result.

How do I avoid duplicates across files?

Define each concept in a single file and reference it from others with links; keep naming consistent so references are unambiguous.