Directory Index System

Maintain directory organization with index files (_index.md, _index.yaml, _index.json) and consistency prompts (_prompt.md) to save context and ensure file consistency across projects.

When to use me

Use this skill when:

• Starting a new project or directory structure
• Onboarding to an existing codebase
• Maintaining consistency across multiple files in a directory
• Documenting directory purpose and contents
• Setting up standards for file creation within directories
• Reducing context switching by providing directory-level guidance
• Creating self-documenting directory structures

What I do

1. Index File Creation & Maintenance

• Create _index files in directories to document contents and purpose
• Support multiple formats: Markdown (default), YAML, or JSON based on project preference
• Track directory contents: List files and subdirectories with brief descriptions
• Document directory purpose: Explain why the directory exists and its role in the project
• Provide navigation guidance: Help users understand how to interact with the directory

2. Consistency Prompt Management

• Create _prompt.md files to guide file creation within directories
• Establish directory-specific standards for naming, formatting, and content
• Provide templates and examples for common file types in the directory
• Maintain consistency across files created by different contributors
• Update prompts as directory standards evolve

3. Context Preservation

• Save directory context to reduce cognitive load when navigating
• Document relationships between files in the directory
• Explain conventions and patterns used within the directory
• Provide entry points for understanding complex directory structures
• Maintain historical context about directory evolution and decisions

4. Navigation Optimization

• Help models choose which directories to explore based on index contents
• Provide quick overviews without needing to examine every file
• Filter irrelevant directories based on documented purposes
• Accelerate understanding of project structure and organization

Index File Formats

Default: Markdown (_index.md)

# Directory: src/components/

## Purpose
Reusable UI components for the application.

## Contents
- **Button/** - Interactive button components
- **Form/** - Form elements and validation components  
- **Layout/** - Page layout and structural components
- **Modal/** - Dialog and overlay components
- **Navigation/** - Menu and navigation components

## Conventions
- Use TypeScript with React
- Follow atomic design principles
- Include Storybook stories
- Export via index.ts barrel files

## Related Directories
- `src/styles/` - Component styling
- `src/hooks/` - Custom React hooks
- `src/utils/` - Utility functions

## Last Updated
2024-03-15 - Added new Modal components

YAML Format (_index.yaml)

directory: src/components/
purpose: Reusable UI components for the application
contents:
  - name: Button
    description: Interactive button components
    type: directory
  - name: Form
    description: Form elements and validation components
    type: directory
  - name: Layout
    description: Page layout and structural components
    type: directory
conventions:
  - Use TypeScript with React
  - Follow atomic design principles
  - Include Storybook stories
related:
  - src/styles/
  - src/hooks/
  - src/utils/
last_updated: 2024-03-15

JSON Format (_index.json)

{
  "directory": "src/components/",
  "purpose": "Reusable UI components for the application",
  "contents": [
    {
      "name": "Button",
      "description": "Interactive button components",
      "type": "directory"
    },
    {
      "name": "Form",
      "description": "Form elements and validation components",
      "type": "directory"
    }
  ],
  "conventions": [
    "Use TypeScript with React",
    "Follow atomic design principles",
    "Include Storybook stories"
  ],
  "related": [
    "src/styles/",
    "src/hooks/",
    "src/utils/"
  ],
  "last_updated": "2024-03-15"
}

Prompt File Format (_prompt.md)

# File Creation Guidelines: src/components/

## When creating new component files in this directory:

### Naming Convention
- Use PascalCase for component names (e.g., `UserProfile.tsx`)
- Use descriptive names that indicate purpose
- Prefix with directory-specific prefixes if needed

### File Structure

ComponentName.tsx # Main component file ComponentName.styles.ts # Component styles (if separate) ComponentName.stories.tsx # Storybook stories ComponentName.test.tsx # Component tests index.ts # Barrel export

### Content Requirements
- Include PropTypes or TypeScript interfaces
- Add JSDoc comments for public APIs
- Follow the existing component patterns
- Include accessibility attributes (aria-*)

### Import/Export Patterns
- Use named exports for components
- Export types/interfaces separately
- Use barrel files (index.ts) for directory exports

### Testing Requirements
- Write unit tests with React Testing Library
- Include accessibility tests
- Test all user interactions
- Mock external dependencies appropriately

### Styling Guidelines
- Use CSS-in-JS (Emotion) for styling
- Follow design system tokens
- Ensure responsive design
- Maintain accessibility color contrast

### Examples
See `Button/` and `Form/` directories for reference implementations.

Examples

# Create index files for current directory
npm run index:create -- --format markdown
npm run index:create -- --format yaml
npm run index:create -- --format json

# Create index files recursively
npm run index:create -- --recursive --format markdown

# Update existing index files
npm run index:update -- --directory src/components/

# Generate prompt file
npm run index:prompt -- --directory src/components/

# Validate index consistency
npm run index:validate -- --directory .

# Convert between formats
npm run index:convert -- --from markdown --to yaml

# Interactive index creation
npm run index:interactive

# Generate directory tree with indexes
npm run index:tree -- --depth 3

# Check for missing indexes
npm run index:check -- --directory .

Output format

Directory Index Report
──────────────────────────────
Directory: /project/src/components/

Index Files:
  ✅ _index.md - Present and up to date
  ✅ _prompt.md - Present and current
  ⚠️ Button/_index.md - Missing prompt file
  ❌ Form/_index.md - Stale (last updated 90 days ago)
  ✅ Layout/_index.md - Present and current

Directory Contents:
  - Button/ (5 files, 1 subdirectory)
  - Form/ (8 files, 2 subdirectories)
  - Layout/ (3 files, 0 subdirectories)
  - Modal/ (4 files, 1 subdirectory)
  - Navigation/ (6 files, 0 subdirectories)

Index Coverage:
  - Directories with index: 5/6 (83%)
  - Directories with prompt: 4/6 (67%)
  - Average index age: 15 days
  - Stale indexes (>30 days): 1

Consistency Check:
  ✅ Naming conventions followed
  ✅ File structures consistent
  ⚠️ Some missing test files
  ✅ Documentation present

Recommendations:
  1. Update Form/_index.md (stale)
  2. Add _prompt.md to Button/ directory
  3. Consider adding index to Modal/utils/ subdirectory
  4. Review test coverage for newer components

Next Actions:
  - Run: npm run index:update -- --directory Form/
  - Run: npm run index:prompt -- --directory Button/
  - Run: npm run index:create -- --directory Modal/utils/

Notes

• Index files should NOT contain detailed contents of subdirectories, only names and general concepts
• Markdown is the default format for readability and ease of editing
• YAML and JSON are available for machine-readable indexes
• Prompt files should be specific to the directory’s purpose and content types
• Indexes should be updated when directory structure or purpose changes significantly
• Balance detail with brevity – indexes should be helpful but not verbose
• Consider version controlling index files alongside code
• Use indexes as living documentation that evolves with the project
• Prompt files help maintain consistency across teams and over time
• The system saves context by documenting directory purpose and relationships