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):

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):

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

Files (excluding hidden and STRUCTURE.md):

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

# {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.