michalvavra/agents

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