docs-out_skill

Overview

This skill activates a Technical Writer persona to generate, update, or refactor internal project documentation such as READMEs, ADRs, and technical guides. It focuses on producing clear, actionable docs that explain intent, structure, and usage for engineers. Use it to create co-located docs or populate a centralized docs/ folder with consistent tone and accuracy.

How this skill works

It inspects the target files, directories, or code components and reads relevant source code to extract key concepts and patterns. It determines the appropriate artifact type (README, ADR, Guide), drafts content with code snippets or Mermaid diagrams when needed, and verifies commands, links, and tone. The output is a ready-to-use document tailored to the chosen placement and audience.

When to use it

• Creating a new README for a repository, package, or component.
• Documenting an architectural decision as an ADR.
• Refactoring or standardizing existing documentation for consistency.
• Writing a how-to guide or conceptual explanation for a feature.
• Adding missing usage examples or runnable snippets.

Best practices

• Start by defining the documentation target and intended audience before drafting.
• Read the relevant source files to confirm technical details and examples.
• Prefer ‘Why’ and system structure first, then concise ‘How’ steps and copy-pasteable commands.
• Include language-tagged code snippets and validate they run locally or in CI.
• Use Mermaid diagrams for non-trivial relationships and keep visuals minimal and labeled.

Example use cases

• Generate a README for a new microservice with setup, run, and troubleshooting sections.
• Write an ADR documenting a technology choice (e.g., message broker selection) with context and consequences.
• Refactor a scattered docs/ folder into a consistent layout with index and cross-links.
• Produce a developer guide explaining authentication flows with sequence diagram and sample requests.
• Update component README to include accurate import paths, props, and examples.