How to use the Commit Archaeologist agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions and optional scripts that an AI coding agent can load when a request matches the skill's description. This one is named commit-archaeologist and is designed for a specific question: why does this code exist?

When you point it at a tracked file and an optional line range, the agent runs a bundled Python script. The script finds the commit that first introduced the code, the later edits, files that often changed alongside it, and clues in commit messages such as reverts, workarounds, and TODOs. The agent then writes a short report with a best-guess explanation and a confidence level.

• Introducing commit: the oldest commit in the selected history
• Timeline: later commits ordered oldest to newest, with detected renames
• Companion files: files that repeatedly changed alongside the target
• Intent signals: issue references, reverts, workarounds, temporary markers and unfinished-work markers from commit messages
• Authors: current blamed-line counts kept separate from historical commit counts

Install Commit Archaeologist

Option 1: download the ZIP of the skill from the directory page and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder so that only that project uses it.

Option 2: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The project's README also lists an install command using the skills CLI. Use it only if you are comfortable with that tool, and check the README for the current details.

• Personal install: ~/.claude/skills/commit-archaeologist
• Project install: .claude/skills/commit-archaeologist inside your repository
• Claude apps: Settings → Capabilities → Skills → upload

Check the requirements

The skill needs Python 3.8 or newer. The script uses only the standard library, so there are no packages to install. Git must be installed and available on your PATH, and the repository you want to investigate must exist as a local clone.

• Python 3.8 or newer
• git installed and on PATH
• A local clone of the repository
• Remote repositories that have not been cloned will not work, because the script reads only local git data

Trigger the skill with natural requests

You do not need to name the script. Ask a question about why code exists, or ask for the history of a function before a rewrite or refactor. The skill's description lists phrases such as "why does this code exist", "who wrote this function and why", and "explain the history of this function".

Give the agent the repository path and file path if it can't infer them. Line ranges work best when you name a current block, such as lines 40-72. The agent will ask only for values that are missing.

• Why does src/cache.py lines 40-72 exist? The repo is at /path/to/repo.
• Who wrote this function and why? It's in src/cache.py.
• Explain the history of the retry block in src/cache.py before I refactor it.
• Before I rewrite this legacy module, show me the history behind the workaround in src/cache.py.

Read the report it produces

The report starts with a bottom line that gives the most likely explanation and a confidence label of high, medium, or low. It then lists the origin, a timeline, companion files, intent evidence, and change risks. Conclusions beyond the commit facts are labelled as inferences.

Current blame ownership is not proof of original authorship, and repeated co-changes suggest coupling rather than a proven dependency. If the commit messages are vague, the report will say so rather than inventing a rationale. The skill also ends with one follow-up offer, such as checking whether the choice looks deliberate or mapping what could break.

• Bottom line with confidence label
• Origin: introducing hash, date, author and subject
• Timeline, oldest to newest
• Companion files as a coupling clue
• Intent evidence quoted from commit subjects
• Change risk to check before editing

Safety notes: scripts and network

The skill runs a bundled Python script, scripts/archaeologist.py. The script is read-only and works offline. The skill's own documentation says it makes no network calls, uses no API keys, and does not write to the repository. Its listed metadata says it runs scripts and does not use the network.

The skill excludes requests to squash, delete or rewrite history, and it does not modify code until you ask. Review the script in the skill folder if you want to confirm this for yourself before running it.

• Runs scripts: yes (scripts/archaeologist.py)
• Uses network: no
• Read-only: no repository writes
• Does not squash, delete or rewrite git history

Tips for better results

Narrow the target. A line range gives a timeline that matches a specific block, while a whole file gives a broader and often longer history. Ask for the range that matches the code you plan to change.

Check the history before a risky rewrite, and treat the confidence label as a prompt to verify, not a verdict. If the origin looks too recent, ask for the whole-file history to compare.

• Use a line range for a specific function or block
• Use the whole file when you want the full history of a module
• Confirm inferences with the commit author or linked issue when possible
• Remember that a shallow or partial clone may not include the full history