---
title: Deepinit Skill for Claude Code
canonical: https://skillselion.com/skills/yeachan-heo/oh-my-claudecode/deepinit
content_type: text/markdown
description: deepinit is an agent-onboarding skill that generates hierarchical AGENTS.md files so developers who use AI coding agents can give every agent a navigable map.
---

# Deepinit Skill

Title: Deepinit Skill for Claude Code

> deepinit is an agent-onboarding skill that generates hierarchical AGENTS.md files so developers who use AI coding agents can give every agent a navigable map.

Canonical: https://skillselion.com/skills/yeachan-heo/oh-my-claudecode/deepinit

deepinit is an agent-onboarding skill that generates hierarchical AGENTS.md files so developers who use AI coding agents can give every agent a navigable map of the entire codebase.

deepinit (level 4) performs deep codebase initialization by writing hierarchical AGENTS.md documentation across directories. Each file documents what a folder contains, component relationships, special instructions, and dependencies, with child files tagged <!-- Parent: ../AGENTS.md --> for navigable trees rooted at /AGENTS.md. Developers reach for deepinit when onboarding Claude Code or other agents to large monorepos, ensuring agents understand directory boundaries without re-scanning the full tree each session. The skill treats AGENTS.md as AI-readable documentation that links parent and child contexts for consistent agent behavior.

## Key facts

- Installs: 1,111
- GitHub stars: 40,938
- Author: Yeachan-Heo
- Repository: Yeachan-Heo/oh-my-claudecode
- Install command: `npx skills add https://github.com/Yeachan-Heo/oh-my-claudecode --skill deepinit`
- Last updated: November 19, 2026

## What Deepinit does

Generate hierarchical AGENTS.md files that give every AI coding agent a clear map of the entire codebase.

How do you document a codebase for AI agents?

Root and nested AGENTS.md files, parent-linked hierarchy tags, and per-directory agent instructions across the repository.

Best for: Developers onboarding AI coding agents to large or nested repositories who need persistent, navigable codebase maps.

Not for: Human-only README updates, single-file scripts, or projects that already maintain complete hierarchical agent docs.

- Creates hierarchical AGENTS.md files across every directory with parent reference tags
- Generates structured documentation including Purpose, Key Files table, and Subdirectories table
- Establishes navigable hierarchy from root AGENTS.md down to every subdirectory
- Produces AI-readable context that improves agent performance on large codebases
- Includes automatic timestamps for generation and last-updated tracking

## SKILL.md

## 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:

```markdown
<!-- Parent: ../AGENTS.md -->
```

This creates a navigable hierarchy:
```
/AGENTS.md                          ← Root (no parent tag)
├── src/AGENTS.md                   ← <!-- Parent: ../AGENTS.md -->
│   ├── src/components/AGENTS.md    ← <!-- Parent: ../AGENTS.md -->
│   └── src/utils/AGENTS.md         ← <!-- Parent: ../AGENTS.md -->
└── docs/AGENTS.md                  ← <!-- Parent: ../AGENTS.md -->
```

### AGENTS.md Template

```markdown
<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
<!-- Generated: {timestamp} | Updated: {timestamp} -->

# {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}

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
```

### 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:
1. Read all files in the directory
2. Analyze purpose and relationships
3. Generate AGENTS.md content
4. Write file with proper parent reference

#### Step 4: Compare and Update (if exists)

When AGENTS.md already exists:

1. **Read existing content**
2. **Identify sections**:
   - Auto-generated sections (can be updated)
   - Manual sections (`<!-- MANUAL -->` preserved)
3. **Compare**:
   - New files added?
   - Files removed?
   - Structure changed?
4. **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 `<!-- Parent: -->` 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 `<!-- Generated: -->` dates | Regenerate outdated files |

Validation script pattern:
```bash
# 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` |
| 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:
```markdown
<!-- Parent: ../AGENTS.md -->
# {Directory Name}

## Purpose
Container directory for organizing related modules.

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `subdir/` | Description (see `subdir/AGENTS.md`) |
```

### Parallelization Rules

1. **Same-level directories**: Process in parallel
2. **Different levels**: Sequential (parent first)
3. **Large directories**: Spawn dedicated agent per directory
4. **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
```markdown
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# 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 install dependencies after modifying the project manifest
- Use TypeScript strict mode
- Follow ESLint rules

### Testing Requirements
- Run tests 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

<!-- MANUAL: Custom project notes can be added below -->
```

#### Nested AGENTS.md
```markdown
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# 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

<!-- MANUAL: -->
```

### Triggering Update Mode

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

1. Detect existing files first
2. Read and parse existing content
3. Analyze current directory state
4. Generate diff between existing and current
5. 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

## Deepinit FAQ

### What does deepinit generate?

deepinit generates hierarchical AGENTS.md files across the codebase. Each directory file explains contents, relationships, and special instructions, with child files linking parents via <!-- Parent: ../AGENTS.md --> tags.

### What is the deepinit skill level?

deepinit is a level 4 skill in oh-my-claudecode focused on deep codebase initialization. It builds a navigable AGENTS.md tree rooted at /AGENTS.md so AI agents understand directory structure and dependencies.

### Is Deepinit safe to install?

skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

## Machine access

- [Sitemap](https://skillselion.com/sitemap.xml)
- [llms.txt](https://skillselion.com/llms.txt)
- [llms-full.txt](https://skillselion.com/llms-full.txt)
- [Developer resources](https://skillselion.com/developers)
- [OpenAPI spec](https://skillselion.com/openapi.json)
- [MCP handshake](https://skillselion.com/.well-known/mcp)
- [API catalog](https://skillselion.com/.well-known/api-catalog)
- [AI catalog](https://skillselion.com/.well-known/ai-catalog.json)
- [Pricing](https://skillselion.com/pricing.md)
- [Auth](https://skillselion.com/auth.md)
- [AGENTS.md](https://skillselion.com/AGENTS.md)
- [Contact](https://skillselion.com/contact)
- [Home](https://skillselion.com/)
