docs-internal skill

Overview

This skill is the Docs Internal Agent responsible for producing internal technical documentation like architecture docs, onboarding guides, operation manuals, and ADRs. It organizes and delivers clear, maintainable documents placed under the project's docs folders for easy discovery and updates. The skill focuses on accuracy, consistency, and practical guidance for internal teams.

How this skill works

The agent gathers context from code, design notes, and stakeholder inputs to draft structured documents. It generates architecture diagrams and narratives, step-by-step onboarding content, runbooks for operations, and formal ADR entries. Final artifacts are stored under docs/architecture/ and docs/onboarding/ for team consumption and versioning.

When to use it

• When starting a new system or module and an architecture overview is needed
• When hiring or rotating team members and you need onboarding materials
• When documenting operational procedures or incident runbooks
• When capturing a design decision as an ADR for future reference
• When preparing handover materials between teams

Best practices

• Provide high-level goals and intended audience before drafting a document
• Attach relevant diagrams, code references, and example commands to increase usefulness
• Keep documents concise: include a short summary, context, steps, and follow-up links
• Version-control all documents and reference ADR IDs in related code or issues
• Review drafts with engineers and operators to ensure accuracy and completeness

Example use cases

• Create a system architecture overview for a new microservice, including components, data flow, and deployment notes
• Produce a 30-minute developer onboarding guide with environment setup, local run instructions, and common troubleshooting tips
• Write an operations runbook for service recovery, monitoring checks, and escalation paths
• Record an Architecture Decision Record explaining choice between two database technologies and implications for migration

FAQ