Project Index

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

---