reference-hunt — Claude Code skill: what it does, how to install
Treats existing source code as a specification and ports its semantics to a target stack when requirements are hard to state in words.
npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a claude-codeWhat reference-hunt does
This skill guides the agent to inspect a repository, vendored folder, or library instead of waiting for written specs. The agent first clarifies what to extract, whether that is runtime behavior, structure, or API conventions. It then drafts a semantics summary covering execution guarantees, edge cases, and differences between language ecosystems.
No target code gets written until the user confirms the semantics summary. Implementation follows idiomatic patterns of the new stack rather than line-by-line transliteration. If the original reference has bugs or inconsistencies, the skill instructs the agent to surface them immediately rather than copying flawed logic.
Before wrapping up, the agent links each expected behavior to the new code and documents any conscious divergence. This structured flow also keeps license constraints in view so unvetted code never lands verbatim in your repository.
What it helps with
- port module behavior from a different programming language
- extract implicit guarantees and edge cases from reference code
- reimplement library functionality without copying its existing bugs
- align on runtime semantics before generating implementation files
Example prompts for the agent
- Port the session logic from src/auth.py to our Rust service using native idioms
- Read the state machine in this folder and write a semantics summary before generating any code
- Recreate the API layer of this service in Go, and flag any license issues first
How to install reference-hunt
1Skills CLI (Vercel)
npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a claude-code2Manually: put the files in place
~/.claude/skills/reference-hunt/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/reference-hunt/
1Skills CLI (Vercel)
npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a codex2Manually: put the files in place
.agents/skills/reference-hunt/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a cursor2Manually: put the files in place
.cursor/skills/reference-hunt/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Neeeophytee/finding-unknowns-skills reference-hunt2Manually: put the files in place
.github/skills/reference-hunt/SKILL.md1Skills CLI (Vercel)
npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a gemini-cli2Platform CLI
gemini skills install https://github.com/Neeeophytee/finding-unknowns-skills --path skills/reference-huntManually: put the files in place
.devin/skills/reference-hunt/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about reference-hunt
How do I install reference-hunt in Claude Code?
Run npx skills add Neeeophytee/finding-unknowns-skills --skill reference-hunt -a claude-code. The skill file will be placed in ~/.claude/skills/reference-hunt/SKILL.md.
What does reference-hunt do?
It instructs the agent to read working source code like a functional specification. The agent analyzes behaviors, error handling, and timing, gets your approval on a summary, and reimplements the logic natively in your stack.
How does the skill handle bugs in the reference code?
It explicitly forbids copying flaws into the new codebase. If the source code contains inconsistencies or errors, the agent must report them to you instead of reproducing them.
Source text
SKILL.md · MIT
--- name: reference-hunt description: Use existing source code as the specification when the user can't describe what they want in words. Use when the user points at a library, module, folder, or site and says "like this," even if it's in a different language or stack. --- # Reference hunt Some requirements are too intricate or too tacit to write down, but working code somewhere already embodies them. The best reference is not a screenshot or a description — it's source. Read it like a spec, then reimplement the semantics, not the syntax. ## Steps 1. Get the reference: a repo path, a vendored folder, a library name, or a site whose underlying code can be read. Ask what specifically to extract from it — behavior, structure, visual system, API shape — so you don't imitate the wrong dimension. 2. Read the reference and produce a **semantics summary** before writing any code: - the behaviors and guarantees it implements (timing, ordering, error handling, edge cases), - the decisions that look deliberate versus incidental, - anything that won't translate to the target language or stack, with a proposed equivalent. 3. Have the user confirm the semantics summary. This is the moment misreadings get caught cheaply. 4. Reimplement in the target stack: same semantics, native idioms. Do not transliterate line by line, and do not copy code verbatim from references whose license doesn't allow it — note the license if it's unclear. 5. Close the loop: list each behavior from the summary and where the new implementation honors it, plus any place you consciously diverged and why. ## Guardrails - The reference defines *what*; the target codebase's conventions define *how*. - If the reference itself turns out to be buggy or inconsistent, surface that instead of faithfully reproducing the bug. - Respect licenses: extracting semantics is fine; copying incompatible code is not.
© Neeeophytee · MIT · Neeeophytee/finding-unknowns-skills
