Skill v1.0.1
currentAutomated scan100/1004 files
version: "1.0.1" 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 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 -->
AGENTS.md Template
<!-- 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, /testsLevel 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 (
<!-- MANUAL -->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 <!-- 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 filesfind . -name "AGENTS.md" -type f# Check parent referencesgrep -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:
<!-- Parent: ../AGENTS.md --># {Directory Name}## PurposeContainer 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
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 --># my-project## PurposeA 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
<!-- Parent: ../AGENTS.md --><!-- Generated: 2024-01-15 | Updated: 2024-01-15 --># components## PurposeReusable 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:
- 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