Progressive Disclosure: Three-phase analysis (Discovery → Deep Analysis → Report)
Multi-Language Support: JavaScript, TypeScript, Python (extensible)
Comprehensive Analysis:
- Code Quality (complexity, duplication, code smells)
- Security (secrets detection, OWASP Top 10, dependency vulnerabilities)
- Testing (coverage analysis, testing trophy distribution)
- Technical Debt (SQALE rating, remediation estimates)
Multiple Report Formats: Markdown, JSON, HTML dashboard
Prioritized Remediation Plans: P0-P3 severity with effort estimates
Industry Standards: Based on 2024-25 SDLC best practices

Installation

Copy the codebase-auditor directory to your Claude skills directory
Ensure Python 3.8+ is installed
No additional dependencies required (uses Python standard library)

Usage with Claude Code

Basic Audit

Audit this codebase using the codebase-auditor skill.

Focused Audit

Run a security-focused audit on this codebase.

Quick Health Check

Give me a quick health check of this codebase (Phase 1 only).

Custom Scope

Audit this codebase focusing on:
- Test coverage and quality
- Security vulnerabilities
- Code complexity

Direct Script Usage

# Full audit with Markdown report
python scripts/audit_engine.py /path/to/codebase --output report.md

# Security-focused audit
python scripts/audit_engine.py /path/to/codebase --scope security --output security-report.md

# JSON output for CI/CD integration
python scripts/audit_engine.py /path/to/codebase --format json --output report.json

# Quick health check only (Phase 1)
python scripts/audit_engine.py /path/to/codebase --phase quick

Output Formats

Markdown (Default)

Human-readable report with detailed findings and recommendations. Suitable for:

Pull request comments
Documentation
Team reviews

JSON

Machine-readable format for CI/CD integration. Includes:

Structured findings
Metrics and scores
Full metadata

HTML

Interactive dashboard with:

Visual metrics
Filterable findings
Color-coded severity levels

Audit Criteria

The skill audits based on 10 key categories:

Code Quality: Complexity, duplication, code smells, file/function length
Testing: Coverage, test quality, testing trophy distribution
Security: Secrets detection, OWASP Top 10, dependency vulnerabilities
Architecture: SOLID principles, design patterns, modularity
Performance: Build times, bundle size, runtime efficiency
Documentation: Code docs, README, architecture docs
DevOps & CI/CD: Pipeline maturity, deployment frequency, DORA metrics
Dependencies: Outdated packages, license compliance, CVEs
Accessibility: WCAG 2.1 AA compliance
TypeScript Strict Mode: Type safety, strict mode violations

See reference/audit_criteria.md for complete checklist.

Severity Levels

Critical (P0): Fix immediately (within 24 hours)
- Security vulnerabilities, secrets exposure, production-breaking bugs
High (P1): Fix this sprint (within 2 weeks)
- Significant quality/security issues, critical path test gaps
Medium (P2): Fix next quarter (within 3 months)
- Code smells, documentation gaps, moderate technical debt
Low (P3): Backlog
- Stylistic issues, minor optimizations

See reference/severity_matrix.md for detailed criteria.

Examples

See the examples/ directory for:

Sample audit report
Sample remediation plan

Architecture

codebase-auditor/
├── SKILL.md                      # Skill definition (Claude loads this)
├── README.md                     # This file
├── scripts/
│   ├── audit_engine.py          # Core orchestrator
│   ├── analyzers/               # Specialized analyzers
│   │   ├── code_quality.py      # Complexity, duplication, smells
│   │   ├── test_coverage.py     # Coverage analysis
│   │   ├── security_scan.py     # Security vulnerabilities
│   │   ├── dependencies.py      # Dependency health
│   │   ├── performance.py       # Performance analysis
│   │   └── technical_debt.py    # SQALE rating
│   ├── report_generator.py      # Multi-format reports
│   └── remediation_planner.py   # Prioritized action plans
├── reference/
│   ├── audit_criteria.md        # Complete audit checklist
│   ├── severity_matrix.md       # Issue prioritization
│   └── best_practices_2025.md   # SDLC standards
└── examples/
    ├── sample_report.md
    └── remediation_plan.md

Extending the Skill

Adding a New Analyzer

Create scripts/analyzers/your_analyzer.py
Implement analyze(codebase_path, metadata) function that returns findings list
Add to ANALYZERS dict in audit_engine.py

Example:

def analyze(codebase_path: Path, metadata: Dict) -> List[Dict]:
    findings = []

    # Your analysis logic here

    findings.append({
        'severity': 'high',
        'category': 'your_category',
        'subcategory': 'specific_issue',
        'title': 'Issue title',
        'description': 'What was found',
        'file': 'path/to/file.js',
        'line': 42,
        'code_snippet': 'problematic code',
        'impact': 'Why it matters',
        'remediation': 'How to fix it',
        'effort': 'low|medium|high',
    })

    return findings

CI/CD Integration

GitHub Actions Example

name: Code Audit

on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Codebase Audit
        run: |
          python codebase-auditor/scripts/audit_engine.py . \
            --format json \
            --output audit-report.json
      - name: Check for Critical Issues
        run: |
          CRITICAL=$(jq '.summary.critical_issues' audit-report.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "❌ Found $CRITICAL critical issues"
            exit 1
          fi

Best Practices

Run Incrementally: For large codebases, use progressive disclosure
Focus on Critical Paths: Audit authentication, payment, data processing first
Baseline Before Releases: Establish quality gates before major releases
Track Over Time: Compare audits to measure improvement
Integrate with CI/CD: Automate for continuous monitoring
Customize Thresholds: Adjust severity based on project maturity

Limitations

Static analysis only (no runtime profiling)
Requires source code access
Dependency data requires internet access (for vulnerability databases)
Large codebases may need chunked analysis

Version

1.0.0 - Initial release

Standards Compliance

Based on:

DORA State of DevOps Report 2024
OWASP Top 10 (2024 Edition)
WCAG 2.1 Guidelines
Kent C. Dodds Testing Trophy
SonarQube Quality Gates

License

Apache 2.0 (example skill for demonstration)

Built with: Python 3.8+ Anthropic Skill Version: 1.0 Last Updated: 2024-10-21