deepinit_skill

Overview

This skill performs deep codebase initialization by generating hierarchical AGENTS.md documentation across every directory. It creates AI-readable notes that explain purpose, key files, subdirectories, dependencies, and agent-specific instructions. The output preserves manual annotations and keeps parent references valid to form a navigable hierarchy.

How this skill works

The skill recursively maps the project tree, excluding common build and vendor folders, then produces AGENTS.md files level by level so parents exist before children. For each directory it reads files, infers purpose and relationships, generates structured sections (Purpose, Key Files, Subdirectories, For AI Agents, Dependencies), and writes or merges content while preserving manual notes. It validates parent links, detects orphans, and can skip empty or generated-only directories according to configurable rules.

When to use it

• Onboarding new engineers or agents to a large or unfamiliar codebase
• Preparing a repository for multi-agent automation and task delegation
• Maintaining up-to-date, AI-friendly documentation across many nested modules
• Before running automated refactors or large-scale changes to ensure context
• As part of CI to detect structural drift and missing documentation

Best practices

• Run generation from project root and ensure parent directories are accessible
• Exclude node_modules, .git, build artifacts, and other large vendor folders
• Preserve manual notes below the <!-- MANUAL --> marker to keep human context
• Process same-level directories in parallel but generate parents before children
• Review and adjust brief file descriptions rather than relying on generic boilerplate

Example use cases

• Generate a root AGENTS.md that lists top-level manifests, scripts, and main subtrees
• Create nested AGENTS.md under src/ that explains core modules, components, and utilities
• Automatically update AGENTS.md after adding or removing directories and preserve manual sections
• Skip empty feature folders while creating minimal AGENTS.md for container directories
• Validate all AGENTS.md parent references and remove or fix orphaned documentation files