Project Index

A skill for analyzing existing codebases and creating structured guidance systems for AI agents. Generates domain-specific knowledge and navigation aids without modifying source code locations.

When to Use

Use this skill when:

• •Starting work on an unfamiliar codebase
• •Creating agent guidance for team projects
• •Setting up structured project documentation
• •Analyzing project architecture and patterns
• •Creating domain-specific agent knowledge (UI, Backend, Database, etc.)

Quick Start

1. •Scan the codebase structure

python ./skills/project-index/scripts/scan_codebase.py /path/to/project --output codebase_index.json

1. •Analyze the generated index and identify domains
2. •Create sub-skills using skill-writer
3. •Generate agent-guidance files

Instructions

Step 1: Scan the Codebase

Run the scanning script to generate a complete structural map:

python ./skills/project-index/scripts/scan_codebase.py <project_path> --output codebase_index.json

Important: The script provides a structural overview. You MUST also:

• •Read key configuration files (package.json, tsconfig.json, etc.)
• •Examine existing code patterns and conventions
• •Understand the project's architecture and dependencies
• •Review README files and existing documentation

Parameters:

• •<project_path>: Absolute path to the project root
• •--output: Output filename (default: codebase_index.json)

Excluded directories: .git, node_modules, __pycache__, dist, build, .next, .expo

Step 2: Analyze the Index

Review the generated codebase_index.json and:

1. •Identify main domains: UI, Backend, Database, API, Components, Utils, etc.
2. •Map relationships: How do domains interact?
3. •Find patterns: Naming conventions, folder structures, architectural patterns
4. •Locate key files: Entry points, configuration files, core modules

CRITICAL: Do not rely solely on the JSON index. Actually explore the codebase:

• •Open and read representative files from each domain
• •Understand the tech stack and frameworks used
• •Identify coding standards and conventions
• •Note any custom patterns or abstractions

Step 3: Create Sub-Skills

For each identified domain, create a focused sub-skill using skill-writer:

# Load the skill-writer skill first, then:
# Create sub-skills like project-index-ui, project-index-backend, etc.

Each sub-skill should:

• •Focus on ONE domain only
• •Include specific navigation guidance
• •Reference relevant agent-guidance files
• •Be discoverable with clear triggers

Use the template: ./skills/project-index/templates/skill-template.md

Naming convention: project-index-<domain> (e.g., project-index-ui, project-index-backend)

Step 4: Generate Agent-Guidance Files

Create agent-<name>.md files in relevant project directories:

Use the template: ./skills/project-index/templates/agent-template.md

Each file should contain:

• •Purpose: Clear description of the directory/section
• •Methodology & Patterns: Design patterns and architectural approaches used
• •Best Practices: Explicit do's and don'ts
• •Key Components/Files: Important files in this section
• •Integration: How to add new elements following existing patterns

Templates

Sub-Skill Template

Location: ./skills/project-index/templates/skill-template.md

---
name: project-index-{{domain}}
description: "Domain-specific knowledge for {{domain}} in this project. Use when working on {{path}} or when user mentions {{domain}}-related tasks."
---

# {{Domain}} Domain Guide

## Overview
Context and purpose of the {{domain}} layer located in `{{path}}`.

## Navigation
- **Main Logic**: [Where core logic resides]
- **Data Flow**: [How data moves through this domain]
- **Key Files**: [Important entry points]

## Guidelines
1. [Specific guideline 1]
2. [Specific guideline 2]

## Reference
See `agent-{{domain}}.md` in the directory for implementation details.

Agent-Guidance Template

Location: ./skills/project-index/templates/agent-template.md

# Agent Guide: {{name}}

## Purpose
Guidance for working in `{{path}}` following established patterns and practices.

## Methodology & Patterns
- **Pattern 1**: [Description]
- **Pattern 2**: [Description]

## Best Practices
- **Do**: [Recommended practice]
- **Avoid**: [Practice to avoid]

## Key Files
- [Important file 1]
- [Important file 2]

## Integration
Follow the structure of `{{example_file}}` when adding new elements.

Best Practices

DO

• •Investigate thoroughly: Read actual code files, not just the index
• •Be specific: Provide concrete examples and file paths
• •Keep it focused: One sub-skill per domain
• •Use skill-writer: Follow proper skill creation workflow
• •Update incrementally: Refine guidance as you learn more
• •Test navigation: Verify agents can find relevant information

AVOID

• •Relying only on scripts: The index is a starting point, not the whole picture
• •Creating mega-skills: Keep each sub-skill focused on one domain
• •Vague descriptions: Be specific about patterns and conventions
• •Duplicating docs: Reference existing READMEs rather than copying
• •Hardcoded assumptions: Note when patterns vary across the codebase

File Structure

.skills/project-index/
├── SKILL.md                    # This file
├── templates/
│   ├── skill-template.md       # Template for sub-skills
│   └── agent-template.md       # Template for agent guides
└── scripts/
    └── scan_codebase.py        # Codebase scanning utility

Advanced Usage

Progressive Enhancement

Start with basic structure analysis, then iteratively improve:

1. •Phase 1: Scan and identify main domains
2. •Phase 2: Create basic sub-skills with navigation
3. •Phase 3: Add detailed agent-guidance files
4. •Phase 4: Refine based on actual usage

Multi-Project Setup

For organizations with multiple projects:

• •Create base patterns in a shared skill
• •Extend with project-specific sub-skills
• •Maintain consistent naming conventions

Validation Checklist

Before considering the index complete:

• • Scanned codebase with script
• • Manually reviewed key files and directories
• • Identified all major domains
• • Created focused sub-skills using skill-writer
• • Generated agent-guidance files in relevant directories
• • Verified navigation paths are clear
• • Tested with sample queries

Troubleshooting

Script fails to run

• •Check Python 3 is installed
• •Verify the project path is absolute and exists
• •Ensure write permissions for output directory

Sub-skills not activating

• •Use skill-writer to validate the skill structure
• •Check description includes trigger words
• •Verify file location matches skill name

Guidance feels incomplete

• •Remember: The index is a living document
• •Add more detail as you work with the codebase
• •Update agent-guidance files based on new discoveries

Credits

Original concept and implementation by b4san.