New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Hierarchical AGENTS.md Generator

by Yeachan-Heo in Yeachan-Heo/oh-my-claudecode

Maps a codebase directory by directory and writes linked AGENTS.md files, each pointing to its parent, to document what each area contains.

MITAuto-check passedAgent Workflows

Install Hierarchical AGENTS.md Generator

skills CLI
$ npx skills add Yeachan-Heo/oh-my-claudecode --skill deepinit -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Yeachan-Heo/oh-my-claudecode deepinit --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Yeachan-Heo/oh-my-claudecode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/deepinit .claude/skills/deepinit && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
deepinit
GitHub stars
40k
Token cost
~2.3k tokens
SKILL.md length
594 words
Files
1
Skills in repo
47
Repo updated
First seen
Licence
MIT

At a glance

Maps a codebase directory by directory and writes linked AGENTS.md files, each pointing to its parent, to document what each area contains.

  • Works in 5 steps: Map Directory Structure → Create Work Plan → Generate Level by Level → …
  • Initializing AI-readable documentation across a large codebase
  • SKILL.md covers Core Concept, Hierarchical Tagging System, Loading Model and AGENTS.md Template, plus 8 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The skill creates hierarchical AGENTS.md documentation across a whole codebase so agents can learn what each directory contains, how components relate, any special instructions for that area, and its dependencies. Every file except the root begins with a visible parent-context line pointing to the parent AGENTS.md, written as prose rather than an HTML comment because Claude Code strips comments before memory reaches the model.

The workflow maps the directory tree with an explore subagent, excluding folders such as node_modules, .git and build output, builds a work plan by depth level, then generates files level by level so parent references are valid. A template defines each file's layout. The skill also explains a loading caveat: stock Claude Code does not load nested AGENTS.md files, so the hierarchy depends on oh-my-claudecode's hooks being active; otherwise a root CLAUDE.md symlink or an @AGENTS.md import is needed and nested files stay unread.

When your agent uses it

  • Initializing AI-readable documentation across a large codebase
  • Creating nested AGENTS.md files that describe each directory
  • Refreshing agent documentation after a big restructure

Example prompts

  • “Run deepinit on this repository and create AGENTS.md files for every directory.”
  • “Generate hierarchical agent docs for the src folder with parent references.”
  • “Refresh the AGENTS.md files after we reorganized the components directory.”

Requirements

  • oh-my-claudecode hooks, so that nested AGENTS.md files are actually loaded

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Map Directory Structure
  2. Create Work Plan
  3. Generate Level by Level
  4. Compare and Update (if exists)
  5. Validate Hierarchy

What it can do on your machine

Read from SKILL.md and the folder at commit 454bae0. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown and bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Hierarchical AGENTS.md Generator loads about 2.3k tokens when it runs. Until then it costs about 20 tokens; SKILL.md has 594 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~20
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Yeachan-Heo/oh-my-claudecode at commit 454bae0, republished under its MIT licence (© Yeachan-Heo). 594 words, ~2,345 tokens.

Download SKILL.mdSave it as .claude/skills/deepinit/SKILL.md (or your agent's skills folder).
name
deepinit
description
Deep codebase initialization with hierarchical AGENTS.md documentation
level
4

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

markdown
**Parent context:** `../AGENTS.md`

This MUST be visible prose, never an HTML comment. Claude Code strips HTML comments before a memory file reaches the model, so <!-- Parent: ... -->, <!-- Generated: ... --> and a commented MANUAL boundary are invisible to the agent that is supposed to act on them.

This creates a navigable hierarchy:

/AGENTS.md                          ← Root (no parent line)
├── src/AGENTS.md                   ← **Parent context:** `../AGENTS.md`
│   ├── src/components/AGENTS.md    ← **Parent context:** `../AGENTS.md`
│   └── src/utils/AGENTS.md         ← **Parent context:** `../AGENTS.md`
└── docs/AGENTS.md                  ← **Parent context:** `../AGENTS.md`

Loading Model

Stock Claude Code discovers nested CLAUDE.md by basename and never loads a nested AGENTS.md; a root @AGENTS.md import does not reach subdirectories either. The nested files generated here are delivered by OMC's PostToolUse directory-context injector, which walks up from each accessed file and injects the nearest AGENTS.md/README.md once per session.

That means the hierarchy requires OMC's hooks to be active. When OMC hooks are disabled (DISABLE_OMC=1, OMC_SKIP_HOOKS=post-tool-use) or the plugin is not registered, add a root-level CLAUDE.md symlink or @AGENTS.md import for the root file and expect nested files to stay unread.

AGENTS.md Template

markdown
# {Directory Name}

**Parent context:** `{relative_path_to_parent}/AGENTS.md`
**Generated:** {timestamp} · **Updated:** {timestamp}

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

Notes under this heading are written by humans and 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 (the ## Manual Notes heading and everything under it are 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:

CheckHow to VerifyCorrective Action
Parent references resolveRead each AGENTS.md, check the **Parent context:** path existsFix path or remove orphan
No orphaned AGENTS.mdCompare AGENTS.md locations to directory structureDelete orphaned files
CompletenessList all directories, check for AGENTS.mdGenerate missing files
Timestamps currentCheck the **Generated:** / **Updated:** datesRegenerate outdated files

Validation script pattern:

bash
# Find all AGENTS.md files
find . -name "AGENTS.md" -type f

# Check parent references
grep -r "\*\*Parent context:\*\*" --include="AGENTS.md" .
Show full SKILL.md (210 more words)Show less

Smart Delegation

TaskAgent
Directory mappingexplore
File analysisarchitect
Content generationwriter
AGENTS.md writeswriter

Empty Directory Handling

When encountering empty or near-empty directories:

ConditionAction
No files, no subdirectoriesSkip - do not create AGENTS.md
No files, has subdirectoriesCreate minimal AGENTS.md with subdirectory listing only
Has only generated files (*.min.js, *.map)Skip or minimal AGENTS.md
Has only config filesCreate AGENTS.md describing configuration purpose

Example minimal AGENTS.md for directory-only containers:

markdown
# {Directory Name}

**Parent context:** `../AGENTS.md`

## 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
# my-project

**Generated:** 2024-01-15 · **Updated:** 2024-01-15

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

Custom project notes can be added under this heading.
Nested AGENTS.md
markdown
# components

**Parent context:** `../AGENTS.md`
**Generated:** 2024-01-15 · **Updated:** 2024-01-15

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

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

© Yeachan-Heo, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/deepinit of Yeachan-Heo/oh-my-claudecode.

Open the folder on GitHubat commit 454bae0

Compare with similar skills

Hierarchical AGENTS.md Generator next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Hierarchical AGENTS.md Generator compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Hierarchical AGENTS.md Generator this skillYeachan-Heo/oh-my-claudecode40k—~2.3kAutomated safety check: PassMIT
Analyze Codebasedivar-ir/ai-doc-gen766—~899Automated safety check: PassMIT
Claude Project Bootstrapmp-web3/claude-starter-kit109—~1.9kAutomated safety check: NotesMIT
Init Deep AGENTS.md Generatorcode-yeongyu/oh-my-openagent70k—~3.5kAutomated safety check: PassCustom licence
Codebase Onboardingaffaan-m/ECC275k1 repos~1.1kAutomated safety check: PassMIT
Codebase Onboardingaffaan-m/ECC275k—~270Automated safety check: PassMIT

Similar skills

  • Analyze Codebase

    divar-ir/ai-doc-gen

    Run a multi-agent deep analysis of a codebase, producing AI-readable analysis documents in .ai/docs/ covering structure, dependencies, data flow, request flow, and APIs.

    766 GitHub stars~899 tokensUpdated 2 mo ago
    Agent WorkflowsAuto-check passed

  • Claude Project Bootstrap

    mp-web3/claude-starter-kit

    Sets up a project for Claude Code by surveying it and writing a .claude folder with a short CLAUDE.md, a CODEBASE.md overview, module docs and optional skills and hooks.

    109 GitHub stars~1.9k tokensUpdated 6 mo ago
    Agent WorkflowsAuto-check: notes

  • Init Deep AGENTS.md Generator

    code-yeongyu/oh-my-openagent

    Generates a tree of AGENTS.md files for a repository, one at the root and more in complex subdirectories, so agents learn its structure and conventions.

    70k GitHub stars~3.5k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Codebase Onboarding

    affaan-m/ECC

    分析一个陌生的代码库，并生成一个结构化的入门指南，包括架构图、关键入口点、规范和一个起始的CLAUDE.md文件。适用于加入新项目或首次在代码仓库中设置Claude Code时。

    275k GitHub starsUsed in 1 repo~1.1k tokens
    DevelopmentAuto-check passed

  • Codebase Onboarding

    affaan-m/ECC

    不慣れなコードベースを分析し、アーキテクチャマップ、主要なエントリポイント、規約、スターターCLAUDE.mdを含む構造化オンボーディングガイドを生成します。新しいプロジェクトに参加するか、リポでClaude Codeを初めてセットアップする場合に使用します。

    275k GitHub stars~270 tokensUpdated 3 days ago
    DevelopmentAuto-check passed

  • Codebase Onboarding

    affaan-m/ECC

    Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CLAUDE.md.

    275k GitHub starsUsed in 3 repos~2k tokens
    DevelopmentAuto-check passed

More from Yeachan-Heo/oh-my-claudecode

All 47 skills in this repo

  • Autopilot

    Yeachan-Heo/oh-my-claudecode

    Takes a short product idea through requirements, design, planning, parallel implementation, QA cycles and multi-reviewer validation to produce working code.

    40k GitHub starsUsed in 1 repo~4.4k tokens
    Auto-check passed

  • OMC HUD Statusline Setup

    Yeachan-Heo/oh-my-claudecode

    Installs and configures the oh-my-claudecode heads-up display in the Claude Code statusline, with minimal, focused and full layouts.

    40k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed

  • Self-Improve Evolutionary Loop

    Yeachan-Heo/oh-my-claudecode

    Runs an autonomous improvement loop on a repository: agents propose and execute plans, a tournament picks the winner by benchmark, and each round is recorded and plotted.

    40k GitHub stars~5.3k tokensUpdated today
    Auto-check: warnings

  • Ask Advisor Routing

    Yeachan-Heo/oh-my-claudecode

    Sends a question or task to another locally installed agent CLI, such as Codex or Gemini, through omc ask and saves the answer as a file.

    40k GitHub stars~572 tokensUpdated today
    Auto-check passed

  • Ask Navigator

    Yeachan-Heo/oh-my-claudecode

    Charts a foggy effort into a map of decision tickets on the repo's issue tracker and works through them one per session, producing decisions rather than deliverables.

    40k GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • OMC Mode Cancellation

    Yeachan-Heo/oh-my-claudecode

    Detects and gracefully cancels whichever OMC mode, autopilot, ralph, swarm, pipeline, or team, is currently active, then clears its state.

    40k GitHub stars~4.6k tokensUpdated today
    Auto-check passed

Categories

Questions about Hierarchical AGENTS.md Generator

What does Hierarchical AGENTS.md Generator do?

Maps a codebase directory by directory and writes linked AGENTS.md files, each pointing to its parent, to document what each area contains. md documentation across a whole codebase so agents can learn what each directory contains, how components relate, any special instructions for that area, and its dependencies.md, written as prose rather than an HTML comment because Claude Code strips comments before memory reaches the model.

When should I use Hierarchical AGENTS.md Generator?

Hierarchical AGENTS.md Generator fits situations like: initializing AI-readable documentation across a large codebase; creating nested AGENTS.md files that describe each directory; refreshing agent documentation after a big restructure.

How do I install Hierarchical AGENTS.md Generator in Claude Code?

Run `npx skills add Yeachan-Heo/oh-my-claudecode --skill deepinit -a claude-code`. Or copy the skill folder (skills/deepinit in Yeachan-Heo/oh-my-claudecode) into .claude/skills/deepinit in your project. Claude Code loads it when a task matches its description.

How do I install Hierarchical AGENTS.md Generator in Codex?

Run `npx skills add Yeachan-Heo/oh-my-claudecode --skill deepinit -a codex`. Or copy the skill folder (skills/deepinit in Yeachan-Heo/oh-my-claudecode) into .agents/skills/deepinit in your project. Codex loads it when a task matches its description.

Can I use Hierarchical AGENTS.md Generator in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Yeachan-Heo/oh-my-claudecode --skill deepinit -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/deepinit, .gemini/skills/deepinit, .github/skills/deepinit and .opencode/skills/deepinit in your project.

What does Hierarchical AGENTS.md Generator need to run?

SKILL.md names no scripts, command-line tools or credentials: Hierarchical AGENTS.md Generator is instructions for the agent only. Our summary lists: oh-my-claudecode hooks, so that nested AGENTS.md files are actually loaded.

Does Hierarchical AGENTS.md Generator access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Hierarchical AGENTS.md Generator safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Hierarchical AGENTS.md Generator use?

Hierarchical AGENTS.md Generator is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Hierarchical AGENTS.md Generator use?

About 2.3k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Hierarchical AGENTS.md Generator?

Skills that share tags, products or a category with Hierarchical AGENTS.md Generator: Analyze Codebase (divar-ir/ai-doc-gen, 766 stars), Claude Project Bootstrap (mp-web3/claude-starter-kit, 109 stars), Init Deep AGENTS.md Generator (code-yeongyu/oh-my-openagent, 70k stars) and Codebase Onboarding (affaan-m/ECC, 275k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Hierarchical AGENTS.md Generator?

Yeachan-Heo (a GitHub user) maintains it in Yeachan-Heo/oh-my-claudecode, which has 39,662 GitHub stars. The repository holds 47 skills in this directory. The repository was last updated on October 7, 2026.

Source: Yeachan-Heo/oh-my-claudecode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.