Generate hierarchical AGENTS.md structure for codebases to optimize AI agent token usage. Use when creating AGENTS.md files, documenting codebase structure, setting up agent guidance, organizing project documentation for AI tools, implementing JIT indexing, or working with monorepos that need lightweight root guidance with detailed sub-folder documentation. Covers repository analysis, root AGENTS.md generation, sub-folder AGENTS.md creation, and token-efficient documentation patterns.
View on GitHubmajesticlabs-dev/majestic-marketplace
majestic-engineer
plugins/majestic-engineer/skills/hierarchical-agents/SKILL.md
February 5, 2026
Select agents to install to:
npx add-skill https://github.com/majesticlabs-dev/majestic-marketplace/blob/main/plugins/majestic-engineer/skills/hierarchical-agents/SKILL.md -a claude-code --skill hierarchical-agentsInstallation paths:
.claude/skills/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