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.

1. Find deployment signals — look for vercel.json, netlify.toml, .github/workflows/,

Dockerfile, docker-compose.yml, Procfile, fly.toml, railway.json.

1. Find data assets — count *.csv, *.json (non-config), *.parquet, *.xlsx,

*.ipynb, *.py script files

1. Find documentation — count *.md, *.pdf, *.docx, *.txt
2. Find CLAUDE.md or agent config files — note their locations and roles
3. 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)

1. PROJECT_REGISTRY — pre-populate with all the projects you found in Domain A and B,

using the exact directory names as keys:

PROJECT_REGISTRY = {
    "my-app": {"id": "my-app", "domain": "A", "status": "live", "url": "myapp.com"},
    "wip-project": {"id": "wip-project", "domain": "B", "status": "dev", "url": ""},
}

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Idadabhai
• Source: Idadabhai/directory-map
• License: MIT

Install and usage instructions live in the source repository linked above.