Skip to content
BeClaude

directory-index-workflow

New
GitHub TrendingDocumentationby annalinneajohansson82

Drop-in templates and setup workflow for placing README.md (directory index) + AGENTS.md (agent navigation rules) in project directories. Use when setting up a new project, onboarding a new agent to an existing project, or creating a new directory that needs an index.

View Source

Summary

md agent navigation rules in project directories.

  • It helps agents and humans navigate a project without scanning every file, reducing context waste and improving efficiency.

Overview

Directory Index Workflow

Place README.md (directory index) and optionally AGENTS.md (agent navigation rules) in project directories so agents and humans can navigate the project without scanning every file.

Templates

1. Root AGENTS.md — project-wide agent rules

Place this at the project root. The "read README first, no bulk-scan" rule covers all subdirectories without needing per-folder AGENTS.md files.

markdown
# Project-wide agent rules

## Directory navigation

- Before working in any directory, read its `README.md` first.
- Do not bulk-scan or recursively read all files in a directory as a discovery
  mechanism. Read individual files only when your task requires their contents.
- The `README.md` in each directory describes what lives there, what each file
  does, and which files can be safely ignored. Use it as a map, not a menu.

## Excluded directories

Do not read or modify files inside these directories unless explicitly
instructed:
- Any directory starting with `.` (hidden directories)
- Build output: `dist/`, `build/`, `_site/`
- Caches: any directory with `cache` in its name
- Dependencies: `node_modules/`, `venv/`
- Auto-generated: `__pycache__/`, `coverage/`
- Excluded: `_ignore/`

## General conventions

[project-specific: build commands, test runners, code style, etc.]

2. Per-directory README.md — the directory index

Place this in each directory you create. Fill in the bracketed sections.

markdown
# <directory-name>

> One-line summary of what lives here.

## Purpose

Brief description — why this directory exists, what it's responsible for.

## Structure

| Path | Purpose |
|---|---|
| `file-or-subdir-name` | What this is / does |
| `file-or-subdir-name` | What this is / does |

## Key files

- **`important-file.ts`** — does X, configured in Y. Only read this if
  you're working on feature Z.
- **`config.ts`** — environment variables and defaults. Read first if
  your task involves configuration changes.

## Files to ignore

- `*.generated.*` — auto-generated, do not modify
- `_legacy/` — kept for reference, not in active use

## Notes

Any gotchas, edge cases, or context an agent needs before touching this
directory. Omit this section if there's nothing to add.

3. Optional per-folder AGENTS.md — directory-level rule overrides

Only add this when a specific directory needs different rules from the root AGENTS.md. Most directories only need the README.md template above.

markdown
# <directory-name> — agent instructions

Override the root AGENTS.md rules for this directory.

## Differences from root

- [List any specific deviation from the global conventions here]

## This directory

- [Directory-specific rules: unusual test setup, special build steps,
  files the agent should always read first, etc.]

## Navigation note

The global rule about reading README.md first still applies unless
explicitly overridden above.

Workflow

Step 1: New project setup

  1. Place the root AGEMENTS.md template at the project root.
  2. Fill in the ## General conventions section with project-specific info (build commands, test runner, code style, deployment).
  3. Create README.md in every non-excluded directory you create using the per-directory template.
  4. Only add per-folder AGEMENTS.md files where the rules genuinely differ from root.

Step 2: New directory

Every time you create a new directory (that isn't in the excluded list):

  1. Write a README.md using the per-directory template.
  2. If the directory needs agent rules that differ from the root, add a per-folder AGEMENTS.md.
  3. Otherwise, the root AGEMENTS.md already covers it — skip.

Step 3: Existing project migration (retrofit)

To retrofit an existing project:

  1. Place the root AGEMENTS.md.
  2. For each existing directory:

- If README.md exists: read it, then add ## Structure and ## Key files sections, preserving existing content. Do not overwrite. - If no README.md exists: write one from the per-directory template.

  1. For each existing directory:

- If AGEMENTS.md exists: read it. Check if it already contains the "read README first, no bulk-scan" navigation rule. If yes, leave it unchanged. If not, add that section. - If no AGEMENTS.md exists: only create one if this directory needs rules that differ from the root. Otherwise the root AGEMENTS.md already covers it — skip.

Directory structure in practice

code
project-root/
├── AGENTS.md              ← global rules (read README first, no bulk-scan)
├── README.md              ← project root README
├── src/
│   ├── README.md          ← "what's in src/ and its subdirs"
│   ├── components/
│   │   ├── README.md      ← "these are the 4 components"
│   │   └── Button.tsx
│   └── utils/
│       ├── README.md      ← "auth.ts, db.ts, helpers"
│       ├── auth.ts
│       └── db.ts
└── tests/
    ├── AGENTS.md           ← only if tests need different rules
    ├── README.md
    └── ...

Excluded directories (do NOT place index files here)

Any directory starting with . (hidden directories), plus:

  • •Build output: dist/, build/, _site/
  • •Caches: any directory with cache in its name
  • •Dependencies: node_modules/, venv/
  • •Auto-generated: __pycache__/, coverage/
  • •Excluded: _ignore/

Install & Usage

1
Create the skills directory
mkdir -p .claude/skills
2
Download the skill file

Add the configuration to .claude/skills/directory-index-workflow.md

3
Invoke in Claude Code
/directory-index-workflow

Use Cases

Setting up a new project with a root AGENTS.md and per-directory README.md files for clear navigation.
Onboarding a new agent to an existing project by adding navigation rules and directory indexes.
Creating a new directory in a project and needing a quick index template for its contents.
Standardizing project documentation across multiple repositories with consistent agent navigation rules.
Reducing token usage and context overhead by preventing agents from bulk-scanning directories.
Adding exclusion rules for build outputs, caches, and dependencies to protect agent focus.

Usage Examples

1

/directory-index-workflow setup my-new-project

2

Add a README.md index to the src/ directory with a description of each file.

3

Generate a root AGENTS.md with rules to read README first and exclude node_modules and dist.

View source on GitHub
agent

Security Audits

LicenseUnknownSourceWarnRepositoryPass

Frequently Asked Questions

What is directory-index-workflow?

This skill provides drop-in templates and a setup workflow for placing README.md directory indexes and AGENTS.md agent navigation rules in project directories. It helps agents and humans navigate a project without scanning every file, reducing context waste and improving efficiency.

How to install directory-index-workflow?

To install directory-index-workflow: create the skills directory (mkdir -p .claude/skills), then add the config to .claude/skills/directory-index-workflow.md. Finally, /directory-index-workflow in Claude Code.

What is directory-index-workflow best for?

directory-index-workflow is a other categorized under Documentation. It is designed for: agent. Created by annalinneajohansson82.

What can I use directory-index-workflow for?

directory-index-workflow is useful for: Setting up a new project with a root AGENTS.md and per-directory README.md files for clear navigation.; Onboarding a new agent to an existing project by adding navigation rules and directory indexes.; Creating a new directory in a project and needing a quick index template for its contents.; Standardizing project documentation across multiple repositories with consistent agent navigation rules.; Reducing token usage and context overhead by preventing agents from bulk-scanning directories.; Adding exclusion rules for build outputs, caches, and dependencies to protect agent focus..