Repo Analyzer Skill

A comprehensive code repository analysis and technical documentation generation skill that scans repositories and generates detailed summary reports.

Purpose

This skill analyzes code repositories to generate comprehensive technical documentation including:

• Repository overview and purpose
• Directory structure and responsibilities
• Technology stack and dependencies
• Core modules and business domains
• Key execution workflows
• Architecture design and extension patterns
• Onboarding guidance
• Risk analysis and technical debt

When to Use This Skill

Use this skill when you need to:

• Understand a new codebase quickly
• Generate technical documentation for a repository
• Analyze repository architecture and dependencies
• Create onboarding guides for new developers
• Assess technical debt and maintenance risks

How It Works

The skill performs an 8-step analysis:

1. Repository Global Scan – Scans directory structure, identifies languages, counts files
2. Project Positioning – Infers project purpose from README, directory names, dependencies
3. Directory Structure Mapping – Analyzes key directory responsibilities and relationships
4. Tech Stack Analysis – Parses dependency files, analyzes technology choices
5. Core Module Abstraction – Identifies core modules and business boundaries
6. Execution Flow Analysis – Traces program startup and typical execution paths
7. Onboarding Path Generation – Creates safe modification points and reading order
8. Risk Assessment – Identifies potential maintenance risks and technical debt

Usage

Basic Usage

python repo_analyzer.py /path/to/repository

With Output File

python repo_analyzer.py /path/to/repository --output report.md

With Custom Depth

python repo_analyzer.py /path/to/repository --depth 3

Parameters

Output Format

The skill generates a comprehensive Markdown report with the following sections:

1. Repository Overview – Project type, purpose, scale, complexity
2. Project Structure – Core directory responsibilities and relationships
3. Technology Stack – Core frameworks, infrastructure, middleware
4. Core Modules & Business Domains – Key business modules and collaboration patterns
5. Key Execution Workflows – Program startup and typical request paths
6. Architecture Design – Architectural style, design patterns, extension paths
7. Quick Start Guide – Recommended reading order, safe modification points
8. Risk Points & Considerations – Potential maintenance risks and pitfalls

Installation

Project-Level Installation

# Copy skill to project .claude directory
cp -r generated-skills/repo-analyzer .claude/skills/

User-Level Installation

# Copy skill to user .claude directory
cp -r generated-skills/repo-analyzer ~/.claude/skills/

Files

• repo_analyzer.py – Main analysis script
• requirements.txt – Python dependencies
• SKILL.md – This documentation file
• examples/ – Example analysis reports

Dependencies

• Python 3.8+
• pyyaml – For parsing YAML configuration files
• toml – For parsing TOML configuration files
• chardet – For file encoding detection

Examples

Analyze Current Repository

python repo_analyzer.py .

Generate Report for Specific Path

python repo_analyzer.py /projects/my-app --output my_analysis.md

Analyze with Custom Settings

python repo_analyzer.py /path/to/repo --depth 3 --include-risks false --verbose true

Limitations

• Analysis is based on static code structure, not runtime behavior
• Business logic inference is limited to code organization patterns
• Dependency analysis requires standard package manager files
• Complex monorepos may require deeper scanning depth

Best Practices

1. Start with default settings – Use depth=2 for most repositories
2. Review inferred information – Always validate inferred project purposes
3. Customize for complex repos – Increase depth for deeply nested structures
4. Combine with manual review – Use the report as a starting point for deeper analysis

Troubleshooting

Common Issues

1. Permission errors – Ensure read access to the repository directory
2. Encoding issues – The skill uses chardet to detect file encodings
3. Missing dependencies – Install required packages from requirements.txt
4. Large repositories – May take longer to process; consider increasing timeout

Debug Mode

Enable verbose logging for detailed processing information:

python repo_analyzer.py /path/to/repo --verbose true

Related Skills

• code-reviewer – For detailed code quality analysis
• architecture-validator – For architectural pattern validation
• dependency-auditor – For security vulnerability scanning

Contributing

To contribute to this skill:

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests if applicable
5. Submit a pull request

License

This skill is released under the MIT License.

Changelog

v1.0.0

• Initial release with 8-step analysis framework
• Support for multiple dependency file formats
• Markdown report generation
• Configurable scanning depth

Note: This skill generates documentation based on code structure analysis. Always validate the generated insights with domain experts and actual code behavior.