# Directory Map > Maps any directory tree into a structured, agent-readable taxonomy. Use this skill whenever the user wants to understand, document, or index a folder or codebase — including requests like "/directory-map", "map this project", "create a project index", "generate a directory overview", "index this repo", "help me understand what's in this folder", "create a DIRECTORY_MAP", or "build an index of this directory". Works on any language, stack, or project type. Produces three outputs: DIRECTORY_MAP.md (human-readable taxonomy), update-index.py (automated re-indexer), and index.json (machine-readable snapshot with an AgentIngress XML block for LLM context injection). - Skill: `idadabhai/directory-map` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add idadabhai/directory-map` - Raw SKILL.md: https://api.skillmd.com/api/skills/idadabhai/directory-map/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: Idadabhai (https://skillmd.com/u/idadabhai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/idadabhai/directory-map --- # Directory Map Skill Produce a semantic audit and automated management framework for any directory. ## Outputs | File | Purpose | |------|---------| | `DIRECTORY_MAP.md` | Human-readable MECE taxonomy + `` XML block | | `update-index.py` | Cross-platform Python re-indexer (copy of `scripts/update-index.py`, customised) | | `index.json` | Machine-readable snapshot (generated by running update-index.py) | All outputs land in the target directory root. Nothing is moved, renamed, or deleted. --- ## Phase 1 — Explore the directory Before writing anything, build a mental model of the directory. Do this in parallel: 1. **List top-level items** — count files vs directories, note approximate total size 2. **Find project configs** — search for `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `composer.json`, `*.csproj`, `Gemfile`. Read the top-level fields (name, version, dependencies) to determine tech stack and project type. 3. **Find deployment signals** — look for `vercel.json`, `netlify.toml`, `.github/workflows/`, `Dockerfile`, `docker-compose.yml`, `Procfile`, `fly.toml`, `railway.json`. 4. **Find data assets** — count `*.csv`, `*.json` (non-config), `*.parquet`, `*.xlsx`, `*.ipynb`, `*.py` script files 5. **Find documentation** — count `*.md`, `*.pdf`, `*.docx`, `*.txt` 6. **Find CLAUDE.md or agent config files** — note their locations and roles 7. **Detect existing index** — if `DIRECTORY_MAP.md` or `index.json` already exist, note their age and offer to refresh rather than overwrite Traverse up to 5 levels deep. Skip: `node_modules`, `.git`, `.next`, `__pycache__`, `.vercel`, `.turbo`, `dist`, `.cache`, `*.lock` directories, `venv`, `.env` (directory). Read `references/taxonomy-guide.md` for the full taxonomy rules and examples. --- ## Phase 2 — Build the MECE taxonomy Based on Phase 1, assign every top-level subdirectory (and files in root) to exactly one of the seven universal domains below. The domains are ordered by strategic importance — revenue-generating or production items first. | Domain | Label | Criteria | |--------|-------|----------| | **A** | Live / Published | Deployed to production OR published package (npm, pip, crates.io, etc.) | | **B** | Active Development | Has code + git but not yet deployed/published | | **C** | Concept / Planning | Strategy docs, PRDs, specs — no runnable code | | **D** | Data & Research Pipelines | Scripts, notebooks, ETL, scraping, data exports | | **E** | Shared Infrastructure | Config files, CI/CD, Dockerfiles, shared tooling, agent memory files | | **F** | Content & Creative Assets | Media, design files, marketing copy, prompt libraries | | **G** | Reference & Archived | Third-party repos, legacy code, dormant past projects | Rules: - Every item gets exactly one domain (MECE — mutually exclusive, collectively exhaustive) - When an item could fit two domains, pick the one that best describes its *primary purpose* - Subdirectories with mixed content get the domain that covers their most important contents - Root-level files (not in any subdirectory) belong to whichever domain fits their purpose; group them under "Root files" in the relevant domain section --- ## Phase 3 — Write DIRECTORY_MAP.md Use the template in `templates/DIRECTORY_MAP.md` as the exact structure to follow. Key rules: - Include the generation timestamp and a "refresh by running update-index.py" note at the top - Write one table per domain (A–G), skipping empty domains - For each project in Domain A or B: include path (relative), tech stack, key dependencies, deployment URL (if known), database, payment processor, and a one-line description - For data pipelines (Domain D): include script count, data export count, and pipeline entry point - For Domain E infrastructure files: list each file with its role in one line - Keep table rows concise — one line per entry, no paragraphs - End with the `` XML block (see Phase 4) --- ## Phase 4 — Append the AgentIngress XML block The `` block goes at the very bottom of `DIRECTORY_MAP.md`, after a horizontal rule. It is machine-readable metadata that lets any LLM load instant context about this directory without running a filesystem scan. Read `references/agentingress.md` for the full schema and an annotated example. Compress it aggressively — no prose, only attributes. Every project in Domain A or B gets a `` element. Every data pipeline in Domain D gets a `` element. Reference repos in Domain G get a `` element. Shared memory files in Domain E go in ``. Always include: - `version="1.0"` and `generated="YYYY-MM-DD"` on the root `` element - `root` attribute pointing to the absolute path of the mapped directory - `refresh` attribute: `"run python update-index.py from this directory"` --- ## Phase 5 — Write update-index.py Copy `scripts/update-index.py` from this skill bundle to the target directory as `update-index.py`. Then customise three sections at the top of the copied file: 1. **`SKIP_DIRS`** — add any project-specific dirs that should be excluded (e.g., large data cache dirs you discovered in Phase 1) 2. **`PROJECT_REGISTRY`** — pre-populate with all the projects you found in Domain A and B, using the exact directory names as keys: ```python PROJECT_REGISTRY = { "my-app": {"id": "my-app", "domain": "A", "status": "live", "url": "myapp.com"}, "wip-project": {"id": "wip-project", "domain": "B", "status": "dev", "url": ""}, } ``` 3. **`ROOT_PATH`** — set to the absolute path of the target directory (as the default, overridable via CLI arg) Run the script after writing it to generate `index.json` and confirm it succeeds. --- ## Phase 6 — Run and report 1. Run `python update-index.py` from the target directory 2. Confirm `index.json` was created with no errors 3. Report to the user: - Files created and their sizes - How many directories, files, and projects were indexed - How many errors (if any) and what they were - The command to refresh the index in future: `python update-index.py` If the script fails, diagnose and fix before reporting success. --- ## What good output looks like A well-executed `/directory-map` leaves the user with: - A `DIRECTORY_MAP.md` they can share with any new Claude session to instantly convey the full project context without re-scanning files - A `update-index.py` they can run in 2 seconds any time the directory changes - An `index.json` they can query programmatically or pass to other tools - An `` block in DIRECTORY_MAP.md that future Claude sessions (and any other LLM) can parse cold without running tools The goal is that a Claude session opened fresh in this directory — with no prior context — can read `DIRECTORY_MAP.md` and immediately know: what lives here, what's live, what's in progress, and where to look for what.