Index of every page on this site: llms.txt
All skills
shubhamsaboo avatar

/commit-archaeologist

@14c5f8f
Run it yourself

Reconstructs why code exists from local git history, including the introducing commit, later changes, current authors, repeated companion files, and likely intent. Use when the user asks "why does this code exist", "who wrote this function and why", or to "explain the history of this function" before a rewrite, refactor, or risky edit. Runs entirely locally.

Use this Skill: https://skilld.dev/gh/shubhamsaboo/awesome-llm-apps/commit-archaeologist

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈96 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈1.5k more on demand in 2 files.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈383 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Commit Archaeologist

git blame names the last person to touch a line. This skill reconstructs the reason the line exists. It traces a file or current line range through local git history, identifies its origin and later edits, finds files that repeatedly changed beside it, and extracts intent clues from commit messages.

Everything runs locally. No network calls, API keys, or repository writes.

When to use

  • The user asks why a block, function, or file exists
  • The user wants to know who introduced code and what changed afterward
  • A rewrite or refactor needs historical constraints and change risks
  • A workaround, temporary branch, or surprising design choice needs context

When not to use

  • The user only wants raw blame output or a commit list
  • The task is to squash, delete, or rewrite git history
  • The repository is remote and has not been cloned locally
  • The question is about project-wide architecture rather than one file or region

Gather the target

Get the repository path and tracked file path. Use a line range when the user names a current block or function. If either path is missing, ask only for the missing value. Do not scan sibling repositories.

Paths should be relative to the repository and use forward slashes. Line ranges use inclusive current line numbers such as 40-72.

Run the dig

From this skill directory:

python3 scripts/archaeologist.py /path/to/repo src/cache.py --lines 40-72 --json

For the complete history of a file, omit --lines:

python3 scripts/archaeologist.py /path/to/repo src/cache.py --json

The script is read-only. With a range it uses git line-log; without one it uses file history with rename following. It also reads current authorship with blame. If it rejects a path or range, report that error and ask for a corrected target.

Before interpreting the JSON, read references/reading-git-history.md. Its confidence rules prevent blame ownership, correlation, and commit-message hints from becoming false certainty.

Read the JSON

  • region: normalized repository, current and historical paths, mode, range, and co-change threshold
  • introduced_by: oldest commit in the selected history
  • timeline: commits ordered oldest to newest, with category, changed files, and detected renames
  • co_changed: files present beside the target in enough selected commits
  • authors: current blamed lines and historical commit counts, kept separate
  • intent_signals: issue references, reverts, workarounds, temporary markers, and unfinished-work markers found in commit messages

An empty signal list means the messages do not say why. It does not mean the change had no reason.

Write the report

Turn the JSON into a short "why this code exists" report:

  1. Bottom line. One or two sentences with the most likely explanation and a confidence label: high, medium, or low.
  2. Origin. Introducing hash, date, author, subject, and the neighboring files that make the initial purpose clearer.
  3. Timeline. Oldest to newest. Group mechanical edits when they do not change the story, but preserve reverts, fixes, and workarounds.
  4. Companion files. Explain repeated co-changes as a coupling clue. Do not treat a one-off file in changed_files as a dependency.
  5. Intent evidence. Quote short commit subjects or signal words. Label any conclusion beyond those facts as an inference.
  6. Change risk. Name the constraints, companion files, and unresolved temporary choices worth checking before an edit.

Keep hashes short in prose, but preserve enough characters to identify them. Do not dump the full JSON unless the user asks.

Evidence rules

  • Current blame ownership is not proof of original authorship.
  • The oldest selected commit is the region's introduction, not always the file's first commit.
  • Repeated co-change suggests coupling; it does not prove a dependency.
  • Commit categories are message heuristics, not verified issue types.
  • "Temporary" and "workaround" are strong intent clues, but only the message author or linked discussion can confirm whether the constraint still applies.
  • If the history is thin or messages are vague, say "the history shows" and "likely" instead of inventing a design rationale.

Follow-ups

End by offering one relevant follow-up, such as:

  • "Want me to assess whether this looks deliberate or accidental?"
  • "Want me to map what could break if this region changes?"

For a deliberate-choice question, weigh repeated edits, issue references, reverts, and explicit constraint words. For a change-risk question, inspect the repeated co-change files and the last behavior-changing commits before proposing edits. Do not modify code until the user asks.

Files

  • scripts/archaeologist.py: offline git history walker and JSON report builder
  • references/reading-git-history.md: interpretation and confidence guide

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts16d3 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides a tool to analyze local git history to explain code changes. It executes git commands through a Python script with robust path validation and argument handling. The skill has a low risk of indirect prompt injection due to its processing of untrusted repository commit history, which is addressed by providing specific interpretation guidelines for the agent.

  • Socket1mo

    No alerts

  • Snyk16d

    Risk: LOW · No issues

Signed by skilld at 14c5f8f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 4 months ago
Other metadata
metadata
{
  "author": "Matt Van Horn",
  "version": "1.0.0",
  "source": "https://github.com/Shubhamsaboo/awesome-llm-apps"
}

README badge

README badge for shubhamsaboo/awesome-llm-apps/commit-archaeologist