archaeologist

Your agents see old code.
This skill makes them dig up why it exists.

Before / After · Install · How it works · Read the skill

---

Strange code often has a reason that the current files no longer show.

archaeologist checks relevant commits, blame, reverts, and tests before removing old logic or replacing an established pattern. It reports only history that changes the decision.

Before / After

Without archaeologist

This duplicate-callback guard is obsolete after the SDK upgrade. I removed it. Tests pass.

The current code looks cleaner. The reason the guard exists was never checked.

With archaeologist

History question: Why does this client suppress a second callback?

Evidence: Commit abc123 added the guard with a regression test for duplicate
callbacks. Commit def456 upgraded the SDK but deliberately retained the test.

Inference: The original SDK defect may be gone, but duplicate-callback behavior
is still a compatibility invariant.

Decision impact: Preserve the invariant while replacing the SDK-specific guard.

Unknown: History does not show whether every downstream caller still depends on it.

History changes the proposal instead of becoming a generic report.

Install

Install with the Skills CLI:

npx skills add Lum1104/archaeologist

Install globally for all projects:

npx skills add Lum1104/archaeologist -g

The repository's root SKILL.md is directly discoverable. No runtime, service, or dependency is installed with it.

Use it

In agents that automatically select installed skills, the description can trigger it when the task matches. Invoke it explicitly when the historical question is easy to miss:

Use the archaeologist skill before removing this retry guard.
Use the archaeologist skill to estimate this API migration from similar changes.
Use the archaeologist skill to check whether this dependency was tried before.

In Codex, use $archaeologist. In Claude Code, use /archaeologist. Invocation syntax may vary in other agents.

Use it for:

• surprising, defensive, or apparently redundant code;
• removals and dependency replacements;
• public API and architecture changes;
• substantial estimates with historical analogues;
• code near previous fixes, regressions, incidents, or reverts.

Skip it for trivial edits whose behavior and intent are already established.

How it works

The agent follows a narrow evidence trail:

Current decision
      ↓
Relevant symbol, file, test, or analogue
      ↓
Origin commits, blame pointers, pickaxe search, fixes, and reverts
      ↓
Evidence / Inference / Unknown
      ↓
Only the findings that change the decision

It stops when more history would not change the proposal. Useful tools include path history, git log -S, git log -G, line blame, commit patches, regression tests, and revert relationships.

Evidence, not mythology

archaeologist does not:

• treat blame as proof of author intent;
• assume an old constraint still applies;
• turn commit size into a precise effort estimate;
• produce biographies, exhaustive timelines, or archaeology for its own sake;
• rewrite history or discard working-tree changes while investigating.

If history is shallow, missing, or inconclusive, the agent says so. Current requirements still win; history is evidence, not authority.

Related skills

• prove-me-wrong attacks the current explanation with a competing one.
• bet-on-it records a prediction before the next causally uncertain experiment or change.
• no-vibes checks whether the final user-visible outcome was actually verified.
• red-button adds focused safeguards when the resulting change is high risk.

Each repository is independent; none of these are required dependencies.

Repository contents

• SKILL.md — instructions loaded by the coding agent.
• LICENSE — MIT license.

License

MIT