repo-activity-summary
Summarize a repository's recent engineering activity from git history — technologies, work types, churn hotspots, contributor patterns, and velocity. Use when asking "what has this repo been working on", "is this project active", "who contributes what", "where are the hotspots",
Install
npx skills add https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/repo-activity-summary
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install codealive-ai-ai-driven-development@llmmart
git clone https://github.com/CodeAlive-AI/ai-driven-development.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole codealive-ai/ai-driven-development collection as a plugin from our marketplace. Git is the plain clone.
README
Repo Activity Summary
Gives AI coding agents a fast answer to "what's been happening in this repo" — without reading every file.
One script, one git log call: no API keys, no network, no dependencies beyond Python 3.9+ and git.
Originally derived from an independent git-signal-extraction tool; maintained here as a stdlib-only Agent Skill.
What you get
A structured report covering:
- Technologies in use (languages, frameworks, tooling) — path heuristics
- Work type breakdown (feature / bugfix / refactor / docs / infra / release / …) — keyword heuristics, with subject samples when classification is unreliable
- Churn hotspots — which files and directories change the most (lockfiles excluded)
- Contributor patterns — who's working on what
- Velocity — commits/week, active days, average commit size (same noise filter)
- Project health — test modules, CI, docs, last activity date
Quick start
python3 scripts/activity_summary.py --repo-dir . --days 90
Useful flags:
| Flag | Description |
|---|---|
--format json |
Machine-readable output |
--author "name" |
Scope to one contributor |
--format text |
Compact one-liner summary |
--classify-threshold 0.25 |
Mark work-type labels unreliable above this unclassified share |
--max-unclassified-samples 40 |
Cap on unclassified subjects in the report |
--raw-subjects |
Emit every filtered commit subject (sha + date + message) |
--branch main |
Analyze a specific branch / revision |
--output report.md |
Write UTF-8 report to a file |
Measured benefit
The skill was benchmarked against the same agent answering the same question without it —
identical prompt, identical clone of simonw/llm
(186 commits / 8 contributors / 90 days), Grok 4.5 in both arms, token and cost figures taken
from the backend's own usage events:
| Without the skill | With the skill | Δ | |
|---|---|---|---|
| Cost | $0.3004 | $0.1748 | −42% |
| Total tokens | 240,251 | 190,694 | −21% |
| Input tokens | 96,497 | 45,901 | −52% |
| Output tokens | 11,274 | 6,937 | −39% |
| Reasoning tokens | 7,975 | 2,291 | −71% |
| Wall clock | 169 s | 106 s | −37% |
Report quality was a tie. Both arms matched a hand-computed ground truth on every mechanical figure (churn ranking, active days, commits/week, line totals, test-module count). The unassisted agent produced a somewhat broader report; the skill-assisted one was more compact. The saving comes from not re-deriving a methodology on every run — hence the 71% drop in reasoning tokens.
What the skill does buy is reproducibility of the mechanical half. Across three runs the
unassisted agent's work-type split swung from 43.5% / 23.1% / 42.5% feature and
3.8% / 18.3% / 5.9% refactor, while churn, velocity, and contributor counts stayed identical
in every skill-assisted run. Interpretation varies either way — which is why the script flags
low-confidence classification instead of asserting it (see below).
Caveats: cost is a single paired measurement on a single mid-size repository. Treat −42% as an order of magnitude, not a guarantee, and expect it to move with repo size and commit-message style.
Design note: facts here, interpretation in the agent
The keyword classifier is deliberately not trusted. When more than --classify-threshold of
commits land in other (25% by default), the report says so in plain text and emits the
unclassified subjects so the calling agent can classify them from the messages themselves.
On simonw/llm that path triggers at 56% — the agent reclassifies and the final report is
correct, whereas asserting the keyword guess would have shipped Other: 56% as the headline
finding. Technology labels carry the same caveat: they are path heuristics, not an import graph.
How it complements investigating-repository-history
That skill answers "why does this specific code exist" at the file/symbol level. This one answers "what has the whole repo been doing" — useful for onboarding, maintenance triage, or understanding a codebase before diving in.
Install
npx skills add CodeAlive-AI/ai-driven-development --skill repo-activity-summary
File structure
repo-activity-summary/
├── SKILL.md ← agent-facing contract
├── README.md ← this file
├── scripts/
│ └── activity_summary.py ← analysis engine (Python 3.9+, stdlib only)
└── tests/
└── test_activity_summary.py ← unittest regression suite
Tests
python3 -m unittest discover -s skills/repo-activity-summary/tests -v
License
MIT
Skill manifest
Repo Activity Summary
Answer "what's been happening in this repo" from local git history — no network, no tokens, no setup.
Trigger conditions
Use this skill when the user asks:
- "What has this repo been working on recently?"
- "What technologies does this project use?"
- "Where are the high-churn files / hotspots?"
- "Who's contributing and what are they working on?"
- "Is this project actively maintained?"
- Before onboarding onto an unfamiliar codebase.
Do not use this skill for file-level blame or provenance — use investigating-repository-history for that.
Quick start
python3 scripts/activity_summary.py --repo-dir . --days 90
| Flag | Default | Description |
|---|---|---|
--repo-dir |
. |
Path to the git repository |
--days |
90 |
Days of history to analyze |
--author |
(all) | Filter to one author |
--format |
markdown |
markdown, json, or text |
--max-commits |
500 |
Cap for very active repos |
--branch |
(current) | Branch / revision to analyze (must not start with -) |
--output / -o |
(stdout) | Write the report to a file (UTF-8) |
--classify-threshold |
0.25 |
If the share of unclassified commits exceeds this fraction, mark work-type classification unreliable and emit subject samples |
--max-unclassified-samples |
40 |
Cap on unclassified commit subjects included in the report |
--raw-subjects |
off | Emit every filtered commit subject with sha and date for agent-side classification |
--version |
— | Print version (1.1.0) and exit |
What it produces
A structured report with:
- Overview — commit count, date range, contributors, lines added/deleted
- Technologies — languages and frameworks inferred from file paths (heuristic)
- Work type breakdown — feature / bugfix / refactor / docs / infra / release / … (keyword heuristic)
- Unclassified subjects — when keyword classification is unreliable, the raw subjects so the agent can classify them
- Churn hotspots — most frequently modified files and directories (lockfiles/generated paths excluded)
- Contributor patterns — per-author commits, lines, and primary focus
- Velocity — commits/week, active days, average commit size (same noise filter as churn)
- Project health — test modules (by basename/path convention), CI, docs, recency
How it works
- Collects commits via
git log --numstat --no-renameswith an explicit UTC--sincetimestamp - Filters bots (GitHub-style
[bot]names and known automation identities) and keeps the filtered count - Detects technologies from extensions, exact manifest filenames, and path segments — never bare path substrings; requires a manifest hit or at least two source files
- Classifies work types with precompiled word-boundary regexes and scored multi-label tie-break; does not present a large "Other" bucket as a finding
- Ranks files/directories by modification frequency
- Aggregates per-author stats using the same classifier
- Checks for test modules, CI config, documentation, and last activity date
Agent guidance
- Prefer the facts in the report (counts, paths, subjects, dates) over the keyword labels.
- When
classification.unreliableis true, or the unclassified share is high, classify from the emitted subjects (or re-run with--raw-subjects) instead of trusting the work-type percentages. - Technology labels are path heuristics, not an import graph — verify against manifests when it matters.
Limitations
- Shallow clones (
--depth 1) limit the analysis window. - Technology detection is a heuristic (extensions, manifests, path segments — not imports or lockfile graphs). Labels are hints.
- Work-type classification is a keyword heuristic, not ground truth. Conventional-commit prefixes classify well; free-form subjects often do not. When the unclassified share exceeds
--classify-threshold(default 25%), the report says so and emits subjects for the agent to classify. - Average commit size and churn exclude lockfiles and common generated/vendor paths; the report states this filter.
- Summarizes activity, not code quality.
Files (ai-driven-development)
-
scripts
-
activity_summary.py 43.8 KB
Loading…
-
-
tests
-
test_activity_summary.py 20.7 KB
Loading…
-
-
README.md 4.7 KB
# Repo Activity Summary Gives AI coding agents a fast answer to "what's been happening in this repo" — without reading every file. One script, one `git log` call: no API keys, no network, no dependencies beyond Python 3.9+ and git. Originally derived from an independent git-signal-extraction tool; maintained here as a stdlib-only Agent Skill. ## What you get A structured report covering: - **Technologies** in use (languages, frameworks, tooling) — path heuristics - **Work type breakdown** (feature / bugfix / refactor / docs / infra / release / …) — keyword heuristics, with subject samples when classification is unreliable - **Churn hotspots** — which files and directories change the most (lockfiles excluded) - **Contributor patterns** — who's working on what - **Velocity** — commits/week, active days, average commit size (same noise filter) - **Project health** — test modules, CI, docs, last activity date ## Quick start ```bash python3 scripts/activity_summary.py --repo-dir . --days 90 ``` Useful flags: | Flag | Description | |------|-------------| | `--format json` | Machine-readable output | | `--author "name"` | Scope to one contributor | | `--format text` | Compact one-liner summary | | `--classify-threshold 0.25` | Mark work-type labels unreliable above this unclassified share | | `--max-unclassified-samples 40` | Cap on unclassified subjects in the report | | `--raw-subjects` | Emit every filtered commit subject (sha + date + message) | | `--branch main` | Analyze a specific branch / revision | | `--output report.md` | Write UTF-8 report to a file | ## Measured benefit The skill was benchmarked against the same agent answering the same question *without* it — identical prompt, identical clone of [`simonw/llm`](https://github.com/simonw/llm) (186 commits / 8 contributors / 90 days), Grok 4.5 in both arms, token and cost figures taken from the backend's own `usage` events: | | Without the skill | With the skill | Δ | |---|---:|---:|---:| | **Cost** | $0.3004 | **$0.1748** | **−42%** | | Total tokens | 240,251 | 190,694 | −21% | | Input tokens | 96,497 | 45,901 | −52% | | Output tokens | 11,274 | 6,937 | −39% | | Reasoning tokens | 7,975 | 2,291 | −71% | | Wall clock | 169 s | 106 s | −37% | **Report quality was a tie.** Both arms matched a hand-computed ground truth on every mechanical figure (churn ranking, active days, commits/week, line totals, test-module count). The unassisted agent produced a somewhat broader report; the skill-assisted one was more compact. The saving comes from not re-deriving a methodology on every run — hence the 71% drop in reasoning tokens. **What the skill does buy is reproducibility of the mechanical half.** Across three runs the unassisted agent's work-type split swung from 43.5% / 23.1% / 42.5% `feature` and 3.8% / 18.3% / 5.9% `refactor`, while churn, velocity, and contributor counts stayed identical in every skill-assisted run. Interpretation varies either way — which is why the script flags low-confidence classification instead of asserting it (see below). Caveats: cost is a single paired measurement on a single mid-size repository. Treat −42% as an order of magnitude, not a guarantee, and expect it to move with repo size and commit-message style. ## Design note: facts here, interpretation in the agent The keyword classifier is deliberately not trusted. When more than `--classify-threshold` of commits land in `other` (25% by default), the report says so in plain text and emits the unclassified subjects so the calling agent can classify them from the messages themselves. On `simonw/llm` that path triggers at 56% — the agent reclassifies and the final report is correct, whereas asserting the keyword guess would have shipped `Other: 56%` as the headline finding. Technology labels carry the same caveat: they are path heuristics, not an import graph. ## How it complements `investigating-repository-history` That skill answers "why does this specific code exist" at the file/symbol level. This one answers "what has the whole repo been doing" — useful for onboarding, maintenance triage, or understanding a codebase before diving in. ## Install ```bash npx skills add CodeAlive-AI/ai-driven-development --skill repo-activity-summary ``` ## File structure ```text repo-activity-summary/ ├── SKILL.md ← agent-facing contract ├── README.md ← this file ├── scripts/ │ └── activity_summary.py ← analysis engine (Python 3.9+, stdlib only) └── tests/ └── test_activity_summary.py ← unittest regression suite ``` ## Tests ```bash python3 -m unittest discover -s skills/repo-activity-summary/tests -v ``` ## License MIT -
SKILL.md 4.8 KB
--- name: repo-activity-summary description: Summarize a repository's recent engineering activity from git history — technologies, work types, churn hotspots, contributor patterns, and velocity. Use when asking "what has this repo been working on", "is this project active", "who contributes what", "where are the hotspots", or before onboarding onto an unfamiliar codebase. license: MIT compatibility: Any coding agent with shell access. Requires git and Python 3.9+. No API keys or network access needed. allowed-tools: Bash(git:*), Bash(python3:*), Read metadata: version: "1.1.0" methodology: "commit-signal-extraction" --- # Repo Activity Summary Answer "what's been happening in this repo" from local git history — no network, no tokens, no setup. ## Trigger conditions Use this skill when the user asks: - "What has this repo been working on recently?" - "What technologies does this project use?" - "Where are the high-churn files / hotspots?" - "Who's contributing and what are they working on?" - "Is this project actively maintained?" - Before onboarding onto an unfamiliar codebase. Do not use this skill for file-level blame or provenance — use `investigating-repository-history` for that. ## Quick start ```bash python3 scripts/activity_summary.py --repo-dir . --days 90 ``` | Flag | Default | Description | |------|---------|-------------| | `--repo-dir` | `.` | Path to the git repository | | `--days` | `90` | Days of history to analyze | | `--author` | *(all)* | Filter to one author | | `--format` | `markdown` | `markdown`, `json`, or `text` | | `--max-commits` | `500` | Cap for very active repos | | `--branch` | *(current)* | Branch / revision to analyze (must not start with `-`) | | `--output` / `-o` | *(stdout)* | Write the report to a file (UTF-8) | | `--classify-threshold` | `0.25` | If the share of unclassified commits exceeds this fraction, mark work-type classification unreliable and emit subject samples | | `--max-unclassified-samples` | `40` | Cap on unclassified commit subjects included in the report | | `--raw-subjects` | *off* | Emit every filtered commit subject with sha and date for agent-side classification | | `--version` | — | Print version (`1.1.0`) and exit | ## What it produces A structured report with: 1. **Overview** — commit count, date range, contributors, lines added/deleted 2. **Technologies** — languages and frameworks inferred from file paths (heuristic) 3. **Work type breakdown** — feature / bugfix / refactor / docs / infra / release / … (keyword heuristic) 4. **Unclassified subjects** — when keyword classification is unreliable, the raw subjects so the agent can classify them 5. **Churn hotspots** — most frequently modified files and directories (lockfiles/generated paths excluded) 6. **Contributor patterns** — per-author commits, lines, and primary focus 7. **Velocity** — commits/week, active days, average commit size (same noise filter as churn) 8. **Project health** — test modules (by basename/path convention), CI, docs, recency ## How it works 1. Collects commits via `git log --numstat --no-renames` with an explicit UTC `--since` timestamp 2. Filters bots (GitHub-style `[bot]` names and known automation identities) and keeps the filtered count 3. Detects technologies from extensions, exact manifest filenames, and path segments — never bare path substrings; requires a manifest hit or at least two source files 4. Classifies work types with precompiled word-boundary regexes and scored multi-label tie-break; does **not** present a large "Other" bucket as a finding 5. Ranks files/directories by modification frequency 6. Aggregates per-author stats using the same classifier 7. Checks for test modules, CI config, documentation, and last activity date ## Agent guidance - Prefer the **facts** in the report (counts, paths, subjects, dates) over the keyword labels. - When `classification.unreliable` is true, or the unclassified share is high, **classify from the emitted subjects** (or re-run with `--raw-subjects`) instead of trusting the work-type percentages. - Technology labels are path heuristics, not an import graph — verify against manifests when it matters. ## Limitations - Shallow clones (`--depth 1`) limit the analysis window. - **Technology detection is a heuristic** (extensions, manifests, path segments — not imports or lockfile graphs). Labels are hints. - **Work-type classification is a keyword heuristic**, not ground truth. Conventional-commit prefixes classify well; free-form subjects often do not. When the unclassified share exceeds `--classify-threshold` (default 25%), the report says so and emits subjects for the agent to classify. - Average commit size and churn exclude lockfiles and common generated/vendor paths; the report states this filter. - Summarizes *activity*, not *code quality*.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.