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 + <AgentIngress> 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 <AgentIngress> XML block (see Phase 4)

---

Phase 4 — Append the AgentIngress XML block

The <AgentIngress> 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 <Project> element. Every data pipeline in Domain D gets a <Pipeline> element. Reference repos in Domain G get a <Repo> element. Shared memory files in Domain E go in <SharedMemory>.

Always include:

• version="1.0" and generated="YYYY-MM-DD" on the root <AgentIngress> 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:

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