Deep codebase initialization with hierarchical AGENTS.md documentation
npxskills add yeachan-heo/oh-my-claudecode--skill deepinitLoading…
Creates comprehensive, hierarchical AGENTS.md documentation across the entire codebase.
AGENTS.md files serve as AI-readable documentation that helps agents understand:
Every AGENTS.md (except root) includes a parent reference tag:
<!-- 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 -->
<!-- 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 -->
Task(subagent_type="explore", model="haiku",
prompt="List all directories recursively. Exclude: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")
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
...
IMPORTANT: Generate parent levels before child levels to ensure parent references are valid.
For each directory:
When AGENTS.md already exists:
<!-- MANUAL --> preserved)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:
# Find all AGENTS.md files
find . -name "AGENTS.md" -type f
# Check parent references
grep -r "<!-- Parent:" --include="AGENTS.md" .
| Task | Agent |
|---|---|
| Directory mapping | explore |
| File analysis | architect |
| Content generation | writer |
| AGENTS.md writes | writer |
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:
<!-- Parent: ../AGENTS.md -->
# {Directory Name}
## Purpose
Container directory for organizing related modules.
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `subdir/` | Description (see `subdir/AGENTS.md`) |
<!-- 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 -->
<!-- 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: -->
When running on an existing codebase with AGENTS.md files:
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).