hierarchical-agents

# Hierarchical Agents Documentation Generator

## Purpose

Create a **hierarchical AGENTS.md system** for codebases that enables AI coding agents to work efficiently with minimal token usage. This skill generates lightweight root documentation with detailed sub-folder guidance following the "nearest-wins" principle.

## When to Use This Skill

Use this skill when:
- Creating AGENTS.md documentation for a new project
- Setting up AI agent guidance for a monorepo
- Optimizing existing documentation for token efficiency
- Restructuring codebase documentation hierarchically
- Implementing JIT (Just-In-Time) indexing patterns
- Need to document complex multi-package repositories

## Core Principles

### 1. Root AGENTS.md is LIGHTWEIGHT
- Only universal guidance and links to sub-files
- ~100-200 lines maximum
- No detailed patterns or examples
- Acts as index and navigation hub

### 2. Nearest-Wins Hierarchy
- Agents read the closest AGENTS.md to the file being edited
- Sub-folder AGENTS.md files override root guidance
- Specific beats general

### 3. JIT (Just-In-Time) Indexing
- Provide paths, globs, and search commands
- NOT full file content
- Enable discovery, not copy-paste
- Commands that agents can execute

### 4. Token Efficiency
- Small, actionable guidance over encyclopedic docs
- Reference files by path, not content
- Examples point to actual files in codebase
- Single-line commands that can be executed

**Why this matters:** Claude Code's system prompt includes ~50 instructions, leaving ~100 usable slots from Claude's ~150 instruction capacity. The system also tells Claude that AGENTS.md context "may or may not be relevant" - so non-universal instructions get ignored uniformly. Manual crafting beats auto-generation for leverage.

### 5. Sub-Folder Detail
- Sub-folder AGENTS.md files have MORE detail
- Specific patterns with file examples
- Technology-specific conventions
- Package-specific commands and gotchas

## Process Overview

Follow these phases in orde