docs-generator

The docs-generator skill provides a systematic approach to technical documentation, specifically engineered for AI-first development environments. By establishing a lightweight, hierarchical documentation structure, it ensures that AI coding agents—such as those utilizing AGENTS.md or agent.d formats—receive contextually relevant information without excessive token consumption. The skill bridges the gap between sprawling, disorganized codebases and the structured requirements of modern AI development tools. It is designed for software architects, backend engineers, and developers working in monorepos or multi-package projects who need to maintain clear, actionable guidance for themselves and their AI counterparts.

• Automatically generates hierarchical documentation trees starting from root-level setup commands down to module-specific implementation details.

• Supports multiple output formats including the standard AGENTS.md, specialized agent.d configuration, and customizable document types.

• Implements a 'nearest-wins' logic, ensuring AI agents prioritize documentation closest to the active file, minimizing noise and hallucinations.

• Provides Just-In-Time (JIT) indexing via search globs, file path maps, and quick-find terminal commands instead of dumping raw file content.

• Facilitates repository analysis to detect tech stacks, build systems, and major directory patterns for tailored documentation layouts.

• Includes pre-flight checks and Definition of Done (DoD) templates to ensure consistency across team commits and PRs.

• Users should confirm the document format (AGENTS.md vs agent.d) and target scope (root vs sub-folder) before execution to maintain project alignment.

• The root documentation should be kept lightweight, ideally under 200 lines, serving as a gateway to more granular sub-folder documentation.

• Always leverage the JIT index features to keep documentation maintainable; avoid duplicating full code blocks within your documentation files.

• Works best when integrated into projects utilizing tools like pnpm workspaces, Turborepo, or Lerna, as it can auto-discover these structure patterns.

• Use the 'common gotchas' and 'patterns & conventions' sections to capture tribal knowledge regarding file organizations and anti-patterns unique to your team.