# Dir Tree Index

> Generate or update distributed STRUCTURE.md index files across a repo to help LLMs orient quickly in project structure and to make large knowledge repositories easier to navigate and summarize.

- Skill: `apocohq/dir-tree-index` (Agent Skill)
- Install (CLI): `npx skillmds@latest add apocohq/dir-tree-index`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apocohq/dir-tree-index/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: apocohq (https://skillmd.com/u/apocohq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/apocohq/dir-tree-index

---


# Dir Tree Index

Generate a `STRUCTURE.md` in every directory, listing its contents with one-line summaries.
This helps LLMs orient themselves quickly, improves discovery in large codebases, and is especially effective for documentation-first or knowledge repository workflows.

## Input

Optional argument: target directory (defaults to repo root).

## Algorithm

Process directories bottom-up (deepest first) so child indexes exist before parents need them.

### Step 1: Discover directories

Replace `<target>` with the resolved path (repo root if no argument given):

```bash
find <target> -type d -not -path '*/.*' | sort -r
```

Process the output in order (deepest first).

### Step 2: For each directory, gather contents

List immediate children. Replace `<dir>` with the directory being processed.

Subdirectories (excluding hidden):

```bash
find <dir> -mindepth 1 -maxdepth 1 -type d -not -name '.*' | sort
```

Files (excluding hidden and STRUCTURE.md):

```bash
find <dir> -mindepth 1 -maxdepth 1 -type f -not -name '.*' -not -name 'STRUCTURE.md' | sort
```

Skip binary files, images, and other non-text files silently.

### Step 3: Build entries

**The files and folders from Step 2 are authoritative.** If a `STRUCTURE.md` already exists, parse it as a summary cache (entry name to summary), but only to avoid re-summarizing unchanged items.

For each child found in Step 2:
- **File, cached:** reuse existing summary.
- **File, new:** read first 30 lines, write a one-line summary.
- **Subdir, cached:** reuse existing summary.
- **Subdir, new:** summarize from its `STRUCTURE.md` (already generated in this pass). If none exists, summarize from folder name.

Remove any entry from the cache that no longer exists on disk.

### Step 4: Write STRUCTURE.md

Write using the format below. Skip the write if content is identical to the existing file (avoid unnecessary git diffs).

After completion, report which directories were created or updated.

## Output Format

```markdown
# {directory name, or "Structure" for root}

*Auto-generated by the `dir-tree-index` skill. Do not edit manually.*

## Folders
- [`subfolder/`](subfolder/) - One-line summary

## Files
- [`README.md`](README.md) - One-line summary
- [`other.md`](other.md) - One-line summary
```

- Use relative markdown links for all entries.
- Always include the auto-generated notice line.
- Omit `## Folders` or `## Files` if that category is empty.
- Sort alphabetically, but put `README.md` first among files.
- Summaries: under 80 chars, sentence fragments, no leading articles, no trailing periods.