write-docs

michalvavra's avatarfrom michalvavra

Write AI-scannable technical documentation.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Technical Writing]

When & Why to Use This Skill

This Claude skill provides a specialized framework for creating AI-scannable technical documentation designed for high performance in LLM-driven workflows. It optimizes documentation for both human readability and machine consumption by enforcing modular structures, YAML frontmatter for metadata, and actionable, example-rich content that improves the accuracy of AI agents and coding assistants.

Use Cases

  • Case 1: Standardizing internal engineering wikis to ensure AI coding assistants can retrieve and process technical context more accurately.
  • Case 2: Developing API documentation with structured tables and copy-pasteable examples to facilitate seamless integration by automated developer tools.
  • Case 3: Refactoring monolithic legacy documentation into modular, concept-based Markdown files to reduce context window noise for LLMs.
  • Case 4: Creating actionable troubleshooting guides and runbooks that AI agents can follow to resolve system incidents autonomously.
namewrite-docs
descriptionWrite 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