# Write Docs

> Write AI-scannable technical documentation.

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

---


# 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