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