mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-28 06:51:16 +08:00
0f6eabb890
Generates a full dedicated Docusaurus page for every one of the 132 skills
(73 bundled + 59 optional) under website/docs/user-guide/skills/{bundled,optional}/<category>/.
Each page carries the skill's description, metadata (version, author, license,
dependencies, platform gating, tags, related skills cross-linked to their own
pages), and the complete SKILL.md body that Hermes loads at runtime.
Previously the two catalog pages just listed skills with a one-line blurb and
no way to see what the skill actually did — users had to go read the source
repo. Now every skill has a browsable, searchable, cross-linked reference in
the docs.
- website/scripts/generate-skill-docs.py — generator that reads skills/ and
optional-skills/, writes per-skill pages, regenerates both catalog indexes,
and rewrites the Skills section of sidebars.ts. Handles MDX escaping
(outside fenced code blocks: curly braces, unsafe HTML-ish tags) and
rewrites relative references/*.md links to point at the GitHub source.
- website/docs/reference/skills-catalog.md — regenerated; each row links to
the new dedicated page.
- website/docs/reference/optional-skills-catalog.md — same.
- website/sidebars.ts — Skills section now has Bundled / Optional subtrees
with one nested category per skill folder.
- .github/workflows/{docs-site-checks,deploy-site}.yml — run the generator
before docusaurus build so CI stays in sync with the source SKILL.md files.
Build verified locally with `npx docusaurus build`. Only remaining warnings
are pre-existing broken link/anchor issues in unrelated pages.
132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
---
|
|
title: "Codebase Inspection"
|
|
sidebar_label: "Codebase Inspection"
|
|
description: "Inspect and analyze codebases using pygount for LOC counting, language breakdown, and code-vs-comment ratios"
|
|
---
|
|
|
|
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
|
|
|
# Codebase Inspection
|
|
|
|
Inspect and analyze codebases using pygount for LOC counting, language breakdown, and code-vs-comment ratios. Use when asked to check lines of code, repo size, language composition, or codebase stats.
|
|
|
|
## Skill metadata
|
|
|
|
| | |
|
|
|---|---|
|
|
| Source | Bundled (installed by default) |
|
|
| Path | `skills/github/codebase-inspection` |
|
|
| Version | `1.0.0` |
|
|
| Author | Hermes Agent |
|
|
| License | MIT |
|
|
| Tags | `LOC`, `Code Analysis`, `pygount`, `Codebase`, `Metrics`, `Repository` |
|
|
| Related skills | [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) |
|
|
|
|
## Reference: full SKILL.md
|
|
|
|
:::info
|
|
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
|
:::
|
|
|
|
# Codebase Inspection with pygount
|
|
|
|
Analyze repositories for lines of code, language breakdown, file counts, and code-vs-comment ratios using `pygount`.
|
|
|
|
## When to Use
|
|
|
|
- User asks for LOC (lines of code) count
|
|
- User wants a language breakdown of a repo
|
|
- User asks about codebase size or composition
|
|
- User wants code-vs-comment ratios
|
|
- General "how big is this repo" questions
|
|
|
|
## Prerequisites
|
|
|
|
```bash
|
|
pip install --break-system-packages pygount 2>/dev/null || pip install pygount
|
|
```
|
|
|
|
## 1. Basic Summary (Most Common)
|
|
|
|
Get a full language breakdown with file counts, code lines, and comment lines:
|
|
|
|
```bash
|
|
cd /path/to/repo
|
|
pygount --format=summary \
|
|
--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
|
|
.
|
|
```
|
|
|
|
**IMPORTANT:** Always use `--folders-to-skip` to exclude dependency/build directories, otherwise pygount will crawl them and take a very long time or hang.
|
|
|
|
## 2. Common Folder Exclusions
|
|
|
|
Adjust based on the project type:
|
|
|
|
```bash
|
|
# Python projects
|
|
--folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"
|
|
|
|
# JavaScript/TypeScript projects
|
|
--folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"
|
|
|
|
# General catch-all
|
|
--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"
|
|
```
|
|
|
|
## 3. Filter by Specific Language
|
|
|
|
```bash
|
|
# Only count Python files
|
|
pygount --suffix=py --format=summary .
|
|
|
|
# Only count Python and YAML
|
|
pygount --suffix=py,yaml,yml --format=summary .
|
|
```
|
|
|
|
## 4. Detailed File-by-File Output
|
|
|
|
```bash
|
|
# Default format shows per-file breakdown
|
|
pygount --folders-to-skip=".git,node_modules,venv" .
|
|
|
|
# Sort by code lines (pipe through sort)
|
|
pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20
|
|
```
|
|
|
|
## 5. Output Formats
|
|
|
|
```bash
|
|
# Summary table (default recommendation)
|
|
pygount --format=summary .
|
|
|
|
# JSON output for programmatic use
|
|
pygount --format=json .
|
|
|
|
# Pipe-friendly: Language, file count, code, docs, empty, string
|
|
pygount --format=summary . 2>/dev/null
|
|
```
|
|
|
|
## 6. Interpreting Results
|
|
|
|
The summary table columns:
|
|
- **Language** — detected programming language
|
|
- **Files** — number of files of that language
|
|
- **Code** — lines of actual code (executable/declarative)
|
|
- **Comment** — lines that are comments or documentation
|
|
- **%** — percentage of total
|
|
|
|
Special pseudo-languages:
|
|
- `__empty__` — empty files
|
|
- `__binary__` — binary files (images, compiled, etc.)
|
|
- `__generated__` — auto-generated files (detected heuristically)
|
|
- `__duplicate__` — files with identical content
|
|
- `__unknown__` — unrecognized file types
|
|
|
|
## Pitfalls
|
|
|
|
1. **Always exclude .git, node_modules, venv** — without `--folders-to-skip`, pygount will crawl everything and may take minutes or hang on large dependency trees.
|
|
2. **Markdown shows 0 code lines** — pygount classifies all Markdown content as comments, not code. This is expected behavior.
|
|
3. **JSON files show low code counts** — pygount may count JSON lines conservatively. For accurate JSON line counts, use `wc -l` directly.
|
|
4. **Large monorepos** — for very large repos, consider using `--suffix` to target specific languages rather than scanning everything.
|