Deep Init Skill

Creates comprehensive, hierarchical AGENTS.md documentation across the entire codebase.

Core Concept

AGENTS.md files serve as AI-readable documentation that helps agents understand:

What each directory contains How components relate to each other Special instructions for working in that area Dependencies and relationships Hierarchical Tagging System

Every AGENTS.md (except root) includes a parent reference tag:

This creates a navigable hierarchy:

/AGENTS.md ← Root (no parent tag) ├── src/AGENTS.md ← │ ├── src/components/AGENTS.md ← │ └── src/utils/AGENTS.md ← └── docs/AGENTS.md ←

AGENTS.md Template

{Directory Name}

Purpose

{One-paragraph description of what this directory contains and its role}

Key Files

{List each significant file with a one-line description}

| File | Description |

|------|-------------|

| file.ts | Brief description of purpose |

Subdirectories

{List each subdirectory with brief purpose}

| Directory | Purpose |

|-----------|---------|

| subdir/ | What it contains (see subdir/AGENTS.md) |

For AI Agents

Working In This Directory

{Special instructions for AI agents modifying files here}

Testing Requirements

{How to test changes in this directory}

Common Patterns

{Code patterns or conventions used here}

Dependencies

Internal

{References to other parts of the codebase this depends on}

External

{Key external packages/libraries used}

Execution Workflow Step 1: Map Directory Structure Task(subagent_type="explore", model="haiku", prompt="List all directories recursively. Exclude: node_modules, .git, dist, build, pycache, .venv, coverage, .next, .nuxt")

Step 2: Create Work Plan

Generate todo items for each directory, organized by depth level:

Level 0: / (root) Level 1: /src, /docs, /tests Level 2: /src/components, /src/utils, /docs/api ...

Step 3: Generate Level by Level

IMPORTANT: Generate parent levels before child levels to ensure parent references are valid.

For each directory:

Read all files in the directory Analyze purpose and relationships Generate AGENTS.md content Write file with proper parent reference Step 4: Compare and Update (if exists)

When AGENTS.md already exists:

Read existing content Identify sections: Auto-generated sections (can be updated) Manual sections ( preserved) Compare: New files added? Files removed? Structure changed? Merge: Update auto-generated content Preserve manual annotations Update timestamp Step 5: Validate Hierarchy

After generation, run validation checks:

Check How to Verify Corrective Action Parent references resolve Read each AGENTS.md, check path exists Fix path or remove orphan No orphaned AGENTS.md Compare AGENTS.md locations to directory structure Delete orphaned files Completeness List all directories, check for AGENTS.md Generate missing files Timestamps current Check dates Regenerate outdated files

Validation script pattern:

Find all AGENTS.md files

find . -name "AGENTS.md" -type f

Check parent references

grep -r "<!-- Parent:" --include="AGENTS.md" .

Smart Delegation Task Agent Directory mapping explore File analysis architect-low Content generation writer AGENTS.md writes writer Empty Directory Handling

When encountering empty or near-empty directories:

Condition Action No files, no subdirectories Skip - do not create AGENTS.md No files, has subdirectories Create minimal AGENTS.md with subdirectory listing only Has only generated files (.min.js, .map) Skip or minimal AGENTS.md Has only config files Create AGENTS.md describing configuration purpose

Example minimal AGENTS.md for directory-only containers:

{Directory Name}

Purpose

Container directory for organizing related modules.

Subdirectories

| Directory | Purpose |

|-----------|---------|

| subdir/ | Description (see subdir/AGENTS.md) |

Parallelization Rules Same-level directories: Process in parallel Different levels: Sequential (parent first) Large directories: Spawn dedicated agent per directory Small directories: Batch multiple into one agent Quality Standards Must Include Accurate file descriptions Correct parent references Subdirectory links AI agent instructions Must Avoid Generic boilerplate Incorrect file names Broken parent references Missing important files Example Output Root AGENTS.md

my-project

Purpose

A web application for managing user tasks with real-time collaboration features.

Key Files

| File | Description |

|------|-------------|

| package.json | Project dependencies and scripts |

| tsconfig.json | TypeScript configuration |

| .env.example | Environment variable template |

Subdirectories

| Directory | Purpose |

|-----------|---------|

| src/ | Application source code (see src/AGENTS.md) |

| docs/ | Documentation (see docs/AGENTS.md) |

| tests/ | Test suites (see tests/AGENTS.md) |

For AI Agents

Working In This Directory

• Always run npm install after modifying package.json
• Use TypeScript strict mode
• Follow ESLint rules

Testing Requirements

• Run npm test before committing
• Ensure >80% coverage

Common Patterns

• Use barrel exports (index.ts)
• Prefer functional components

Dependencies

External

• React 18.x - UI framework
• TypeScript 5.x - Type safety
• Vite - Build tool

Nested AGENTS.md

components

Purpose

Reusable React components organized by feature and complexity.

Key Files

| File | Description |

|------|-------------|

| index.ts | Barrel export for all components |

| Button.tsx | Primary button component |

| Modal.tsx | Modal dialog component |

Subdirectories

| Directory | Purpose |

|-----------|---------|

| forms/ | Form-related components (see forms/AGENTS.md) |

| layout/ | Layout components (see layout/AGENTS.md) |

For AI Agents

Working In This Directory

• Each component has its own file
• Use CSS modules for styling
• Export via index.ts

Testing Requirements

• Unit tests in __tests__/ subdirectory
• Use React Testing Library

Common Patterns

• Props interfaces defined above component
• Use forwardRef for DOM-exposing components

Dependencies

Internal

• src/hooks/ - Custom hooks used by components
• src/utils/ - Utility functions

External

• clsx - Conditional class names
• lucide-react - Icons

Triggering Update Mode

When running on an existing codebase with AGENTS.md files:

Detect existing files first Read and parse existing content Analyze current directory state Generate diff between existing and current Apply updates while preserving manual sections Performance Considerations Cache directory listings - Don't re-scan same directories Batch small directories - Process multiple at once Skip unchanged - If directory hasn't changed, skip regeneration Parallel writes - Multiple agents writing different files simultaneously