Repo Intel Skill
Build and maintain a cached repo-intel artifact using the agent-analyzer binary. Covers git history, AST symbols, project metadata, doc-code sync, and (after enrich) LLM-generated per-file descriptors and a 3-depth narrative summary.
Parse Arguments
const allArgs = '$ARGUMENTS'.split(' ').filter(Boolean);
const positional = allArgs.filter(a => !a.startsWith('--'));
const action = positional[0] || 'status';
const queryType = action === 'query' ? positional[1] : null;
const queryArg = action === 'query' ? positional[2] || null : null;
Primary Responsibilities
- Initialize artifact on demand (
/repo-intel init) - full scan
- Update incrementally (
/repo-intel update) - only new commits since last run
- Enrich with LLM signals (
/repo-intel enrich) - spawn the repo-intel-summarizer and repo-intel-weighter Haiku subagents to populate the artifact's summary (3 depths) and fileDescriptors (top-500 most-active files). The Rust binary itself never calls an LLM - this orchestration runs in JS and pipes the agent JSON back through set-summary / set-descriptors.
- Check status (
/repo-intel status)
- Run queries against the cached artifact (
/repo-intel query <type>)
Binary Integration
const pluginRoot = '$CLAUDE_PLUGIN_ROOT';
const binary = require(`${pluginRoot}/lib/binary`);
const repoIntel = require(`${pluginRoot}/lib/repo-intel`);
The binary is resolved and auto-downloaded if needed via binary.ensureBinary(). The binary module is bundled with this plugin - no external dependency required.
Core Data Contract
Artifact is stored in the platform state directory:
- Claude Code:
.claude/repo-intel.json
- OpenCode:
.opencode/repo-intel.json
- Codex CLI:
.codex/repo-intel.json
Available Queries
All queries delegate to agent-analyzer repo-intel query <type>.
Git History (Phase 1)
| Query |
Description |
hotspots |
Recency-weighted most-changed files |
coldspots |
Least-changed files with no recent activity |
bugspots |
Files with highest bug-fix density (fix/change ratio) |
coupling <file> |
Files that change together with <file> |
ownership <path> |
Who owns a directory or file |
bus-factor |
Detailed bus factor with critical owners and at-risk areas |
norms |
Commit message conventions detected from history |
areas |
Directory-level health overview |
contributors |
Contributors sorted by commit count with staleness |
release-info |
Release cadence and last release |
health |
Repository health summary |
file-history <file> |
Detailed history for a specific file |
conventions |
Commit message style, prefixes, scope usage |
test-gaps |
Hot source files with no co-changing test file |
diff-risk <files> |
Score changed files by composite risk |
doc-drift |
Doc files with low code coupling (likely stale) |
onboard |
Newcomer-oriented repo summary |
can-i-help |
Contributor guidance matching skills to areas needing work |
entry-points |
Every place execution can start (binaries, main functions, npm scripts) |
AST Symbols (Phase 2)
| Query |
Description |
painspots |
Files ranked by hotspot x (1 + bug_rate) x (1 + complexity/30) |
symbols <file> |
AST exports, imports, and definitions for a file |
dependents <symbol> |
Files that import a given symbol (reverse dependency) |
Doc-Code Sync (Phase 4)
| Query |
Description |
stale-docs |
Doc files with stale references to source symbols |
LLM-Augmented Signals (Phase 6, requires /repo-intel enrich first)
| Query |
Description |
find <concept> |
Concept-to-file search. Replaces grep -r <concept> with a ranked list and a one-line why per result. Without descriptors, scores from path/symbol/import/doc-header substring matches; with descriptors (populated by enrich), also catches semantic synonyms (worker ↔ executor) by matching against the per-file LLM descriptor. |
summary [--depth 1|3|10] |
Cached 3-depth narrative description of the repo. depth1 = one sentence, depth3 = one paragraph, depth10 = one-page technical overview. Generated by the repo-intel-summarizer Haiku agent at enrich time. |
Slop Targeting (Phase 7, fed to /deslop)
| Query |
Description |
slop-fixes |
Pinpoint structured fix actions for Haiku-tier execution: tracked artifacts, stale CI configs, duplicate tooling, orphan exports, empty catches, tautological tests. Each finding has a file + line range + action so the agent applies it without further research. |
slop-targets |
Ranked targets for Sonnet (file-level) and Opus (cross-file) scans. Sonnet: defensive cargo cult, bot-authored, could-be-shorter. Opus: cliché clusters, wrapper towers, single-impl traits, high-bug communities. With the embedder installed, also: stylistic outliers, semantic duplicates. |
Embedder Actions (Phase 7, opt-in)
| Action |
Description |
embed status |
Show whether the embedder is installed, which variant + detail level, sidecar size and last-update time. |
embed update |
Delta re-embed only files whose content hash differs from the existing sidecar. Falls back to full scan if no sidecar exists. Pipes JSON to set-embeddings. |
embed reset |
Clear the cached embedder preference so the next /repo-intel enrich re-prompts. Does not delete the sidecar or downloaded model — use this when changing model variant or detail level. |
Post-Init Enrichment
Two Haiku-backed Task subagents fire when /repo-intel enrich runs:
repo-intel-weighter reads the top-500 most-active files in batches of 30, returns 1-2 sentence concrete descriptors per file as JSON between marker blocks. The skill parses the markers and pipes the JSON to agent-analyzer repo-intel set-descriptors --input -.repo-intel-summarizer reads README + manifests + top-10 hotspot file headers, returns {depth1, depth3, depth10, inputHash} as JSON between marker blocks. The skill parses and pipes to set-summary --input -.
The Rust binary itself never makes LLM calls. All orchestration lives here.
Embedder (opt-in)
enrich also runs agent-analyzer-embed when the user has opted in. The choice is captured by two AskUserQuestion prompts on first use, persisted in <stateDir>/sources/preference.json:
embedder — none (default), small (BGE-small Q8 ~30 MB), or big (EmbeddingGemma-300M Q4 ~195 MB)embedderDetail — compact (per-file × 128 dim), balanced (per-function × 256 dim, recommended), maximum (per-function × 768 dim)
Subsequent enrich runs read the cached preference and proceed silently. The embed binary downloads the model file on first use (cached next to the binary in ~/.agent-sh/bin/); model files are not bundled in the binary.
Embeddings live in a sidecar file <map_stem>.embeddings.bin next to the JSON artifact (packed fp16, deterministic). The main JSON stays diffable; the sidecar is opaque binary.
When the embedder is not installed, all queries that benefit from embeddings (find, slop-targets) work in their AST/graph-only mode — same shape, weaker signals.
Behavior Rules
- Never call the binary without
binary.ensureBinary() first
- Always cache results after a successful init or update
- Prefer incremental update unless artifact is missing
- Return structured data - let the command layer format output
Recency and Staleness
- Recency window: 90 days relative to the repo's
lastCommitDate (not wall clock)
- Stale contributor:
lastSeen > 90 days before lastCommitDate
- Hotspot score:
(recentChanges * 2 + totalChanges) / (totalChanges + 1)
- Area health: "healthy" / "needs-attention" / "at-risk"
Output Expectations
- init/update: commit count, files analyzed, last commit, duration
- status: age, staleness, commits behind HEAD
- query: ranked list with scores, truncated to
--limit (default 10)
1---2name: repo-intel-23description: Use when user asks to "analyze git history", "show hotspots", "coldspots", "file coupling", "code ownership", "bus factor", "bugspots", "area health", "project norms", "test gaps", "untested files", "diff risk", "stale docs", "doc drift", "contributors", "repo health", "release cadence", "file history", "conventions", "AST symbols", "find dependents", "pain spots", "onboard to codebase", "where can I help", "find <concept>", "find auth code", "find worker pool", "summarize this repo", "repo summary", "what does this project do", "enrich repo-intel", "generate descriptors", "entry points", "where does this start", "slop fixes", "clean slop", "slop targets", "deslop targets", "semantic find", "find similar function", "semantic duplicate", "stylistic outlier", "embed update", "embed status", "embed reset", "repo-intel init/update/enrich/status/query/embed". Builds and queries a cached repo-intel artifact using the agent-analyzer binary; spawns Haiku subagents post-init for descriptors and a 3-depth narrative sum4---56# Repo Intel Skill78Build and maintain a cached repo-intel artifact using the agent-analyzer binary. Covers git history, AST symbols, project metadata, doc-code sync, and (after `enrich`) LLM-generated per-file descriptors and a 3-depth narrative summary.910## Parse Arguments1112```javascript13const allArgs = '$ARGUMENTS'.split(' ').filter(Boolean);14const positional = allArgs.filter(a => !a.startsWith('--'));15const action = positional[0] || 'status';16const queryType = action === 'query' ? positional[1] : null;17const queryArg = action === 'query' ? positional[2] || null : null;18```1920## Primary Responsibilities21221. **Initialize artifact** on demand (`/repo-intel init`) - full scan232. **Update incrementally** (`/repo-intel update`) - only new commits since last run243. **Enrich with LLM signals** (`/repo-intel enrich`) - spawn the `repo-intel-summarizer` and `repo-intel-weighter` Haiku subagents to populate the artifact's `summary` (3 depths) and `fileDescriptors` (top-500 most-active files). The Rust binary itself never calls an LLM - this orchestration runs in JS and pipes the agent JSON back through `set-summary` / `set-descriptors`.254. **Check status** (`/repo-intel status`)265. **Run queries** against the cached artifact (`/repo-intel query <type>`)2728## Binary Integration2930```javascript31const pluginRoot = '$CLAUDE_PLUGIN_ROOT';32const binary = require(`${pluginRoot}/lib/binary`);33const repoIntel = require(`${pluginRoot}/lib/repo-intel`);34```3536The binary is resolved and auto-downloaded if needed via `binary.ensureBinary()`. The binary module is bundled with this plugin - no external dependency required.3738## Core Data Contract3940Artifact is stored in the platform state directory:4142- Claude Code: `.claude/repo-intel.json`43- OpenCode: `.opencode/repo-intel.json`44- Codex CLI: `.codex/repo-intel.json`4546## Available Queries4748All queries delegate to `agent-analyzer repo-intel query <type>`.4950### Git History (Phase 1)5152| Query | Description |53|-------|-------------|54| `hotspots` | Recency-weighted most-changed files |55| `coldspots` | Least-changed files with no recent activity |56| `bugspots` | Files with highest bug-fix density (fix/change ratio) |57| `coupling <file>` | Files that change together with `<file>` |58| `ownership <path>` | Who owns a directory or file |59| `bus-factor` | Detailed bus factor with critical owners and at-risk areas |60| `norms` | Commit message conventions detected from history |61| `areas` | Directory-level health overview |62| `contributors` | Contributors sorted by commit count with staleness |63| `release-info` | Release cadence and last release |64| `health` | Repository health summary |65| `file-history <file>` | Detailed history for a specific file |66| `conventions` | Commit message style, prefixes, scope usage |67| `test-gaps` | Hot source files with no co-changing test file |68| `diff-risk <files>` | Score changed files by composite risk |69| `doc-drift` | Doc files with low code coupling (likely stale) |70| `onboard` | Newcomer-oriented repo summary |71| `can-i-help` | Contributor guidance matching skills to areas needing work |72| `entry-points` | Every place execution can start (binaries, `main` functions, npm scripts) |7374### AST Symbols (Phase 2)7576| Query | Description |77|-------|-------------|78| `painspots` | Files ranked by hotspot x (1 + bug_rate) x (1 + complexity/30) |79| `symbols <file>` | AST exports, imports, and definitions for a file |80| `dependents <symbol>` | Files that import a given symbol (reverse dependency) |8182### Doc-Code Sync (Phase 4)8384| Query | Description |85|-------|-------------|86| `stale-docs` | Doc files with stale references to source symbols |8788### LLM-Augmented Signals (Phase 6, requires `/repo-intel enrich` first)8990| Query | Description |91|-------|-------------|92| `find <concept>` | Concept-to-file search. Replaces `grep -r <concept>` with a ranked list and a one-line `why` per result. Without descriptors, scores from path/symbol/import/doc-header substring matches; with descriptors (populated by `enrich`), also catches semantic synonyms (worker ↔ executor) by matching against the per-file LLM descriptor. |93| `summary [--depth 1\|3\|10]` | Cached 3-depth narrative description of the repo. depth1 = one sentence, depth3 = one paragraph, depth10 = one-page technical overview. Generated by the `repo-intel-summarizer` Haiku agent at `enrich` time. |9495### Slop Targeting (Phase 7, fed to `/deslop`)9697| Query | Description |98|-------|-------------|99| `slop-fixes` | Pinpoint structured fix actions for Haiku-tier execution: tracked artifacts, stale CI configs, duplicate tooling, orphan exports, empty catches, tautological tests. Each finding has a file + line range + action so the agent applies it without further research. |100| `slop-targets` | Ranked targets for Sonnet (file-level) and Opus (cross-file) scans. Sonnet: defensive cargo cult, bot-authored, could-be-shorter. Opus: cliché clusters, wrapper towers, single-impl traits, high-bug communities. With the embedder installed, also: stylistic outliers, semantic duplicates. |101102### Embedder Actions (Phase 7, opt-in)103104| Action | Description |105|--------|-------------|106| `embed status` | Show whether the embedder is installed, which variant + detail level, sidecar size and last-update time. |107| `embed update` | Delta re-embed only files whose content hash differs from the existing sidecar. Falls back to full scan if no sidecar exists. Pipes JSON to `set-embeddings`. |108| `embed reset` | Clear the cached embedder preference so the next `/repo-intel enrich` re-prompts. Does not delete the sidecar or downloaded model — use this when changing model variant or detail level. |109110## Post-Init Enrichment111112Two Haiku-backed Task subagents fire when `/repo-intel enrich` runs:113114- **`repo-intel-weighter`** reads the top-500 most-active files in batches of 30, returns 1-2 sentence concrete descriptors per file as JSON between marker blocks. The skill parses the markers and pipes the JSON to `agent-analyzer repo-intel set-descriptors --input -`.115- **`repo-intel-summarizer`** reads README + manifests + top-10 hotspot file headers, returns `{depth1, depth3, depth10, inputHash}` as JSON between marker blocks. The skill parses and pipes to `set-summary --input -`.116117The Rust binary itself never makes LLM calls. All orchestration lives here.118119## Embedder (opt-in)120121`enrich` also runs `agent-analyzer-embed` when the user has opted in. The choice is captured by two `AskUserQuestion` prompts on first use, persisted in `<stateDir>/sources/preference.json`:1221231. `embedder` — `none` (default), `small` (BGE-small Q8 ~30 MB), or `big` (EmbeddingGemma-300M Q4 ~195 MB)1242. `embedderDetail` — `compact` (per-file × 128 dim), `balanced` (per-function × 256 dim, recommended), `maximum` (per-function × 768 dim)125126Subsequent enrich runs read the cached preference and proceed silently. The embed binary downloads the model file on first use (cached next to the binary in `~/.agent-sh/bin/`); model files are not bundled in the binary.127128Embeddings live in a sidecar file `<map_stem>.embeddings.bin` next to the JSON artifact (packed fp16, deterministic). The main JSON stays diffable; the sidecar is opaque binary.129130When the embedder is not installed, all queries that benefit from embeddings (`find`, `slop-targets`) work in their AST/graph-only mode — same shape, weaker signals.131132## Behavior Rules133134- **Never** call the binary without `binary.ensureBinary()` first135- **Always** cache results after a successful init or update136- **Prefer** incremental update unless artifact is missing137- **Return** structured data - let the command layer format output138139## Recency and Staleness140141- **Recency window**: 90 days relative to the repo's `lastCommitDate` (not wall clock)142- **Stale contributor**: `lastSeen` > 90 days before `lastCommitDate`143- **Hotspot score**: `(recentChanges * 2 + totalChanges) / (totalChanges + 1)`144- **Area health**: "healthy" / "needs-attention" / "at-risk"145146## Output Expectations147148- **init/update**: commit count, files analyzed, last commit, duration149- **status**: age, staleness, commits behind HEAD150- **query**: ranked list with scores, truncated to `--limit` (default 10)
agent-sh