codebase-inspection

The codebase-inspection skill provides a robust interface for measuring software project metrics using the pygount tool. It is designed for developers, project managers, and auditors who need to understand the structural composition, physical size, and documentation density of a codebase. By generating detailed summaries of lines of code (LOC), file counts by language, and the ratio of executable code to comments, it helps teams track technical debt, verify project scale, and perform repository audits. This skill is particularly useful when onboarding into new projects, preparing for code reviews, or performing high-level analysis on complex monorepos.

• Automatically calculates total lines of code, blank lines, and comment lines for entire repositories or specific subdirectories.

• Generates language-specific breakdown reports to identify the technology stack and dominant languages within a project.

• Provides granular visibility into code-vs-comment ratios, aiding in the assessment of documentation quality and maintenance health.

• Supports various output formats including human-readable summaries and machine-parsable JSON for downstream integration.

• Includes pre-configured folder exclusion logic to safely ignore dependency directories like node_modules, venv, and .git, preventing processing hang-ups.

• Always utilize the --folders-to-skip flag to filter out build artifacts, package dependencies, and version control files to ensure rapid and accurate execution.

• Use the --suffix parameter when targeting specific programming languages to narrow the scope of analysis in massive monorepos.

• Interpret the 'pseudo-languages' in the summary output—such as binary, generated, and duplicate—to accurately understand how files are classified by the engine.

• Be aware that documentation-heavy formats like Markdown are categorized by pygount as comments, resulting in zero code lines; use supplemental tools like wc for plaintext files if necessary.

• Ensure the pygount utility is installed in the agent's environment; the skill provides a fallback installation command for various Linux/macOS environments.