Guide · Agent skill
How to use the Spec Miner agent skill for legacy code
Updated · written with AI from the project's own documentation and checked against our catalogue data
Spec Miner is an agent skill that makes an AI agent act as a reverse-engineering specialist for code that has little or no documentation. It is aimed at developers who have inherited a legacy project, or who need to understand an old system before changing it. After following this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check in its output.
Spec MinerJeffallan/claude-skills · MIT Download the skill Quick start
- 1Download the skill. Download the spec-miner ZIP from this page. The file contains SKILL.md and a references folder.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder for one project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 4Ask in plain language. Describe the legacy or undocumented part you need explained, using a trigger phrase such as 'reverse engineer' or 'no documentation'.
- 5Review the report. Open specs/{project_name}_reverse_spec.md, check the uncertainties section, and verify key observations against the cited code.
What does the Spec Miner skill make the agent do?
Without this skill, an agent asked about an undocumented project may guess. Spec Miner tells the agent to explore the project's files, search them, read them, and trace how data and requests move through the code. The goal is a written specification that describes the behaviour the agent actually observed in the code.
The skill has the agent work from two perspectives: an architecture view for system structure and data flows, and a QA view for observable behaviour and edge cases. Observations are written in EARS, a structured 'shall' style (for example, 'When a request lacks an auth token, the system shall return HTTP 401.'). The result is saved as a report in a specs folder, with uncertainties listed separately from confirmed facts.
- Maps the project's structure, entry points, routes and data models
- Traces data flows and request paths through the code
- Writes observed behaviour as EARS-style requirements with code locations
- Flags areas that need clarification rather than filling gaps with guesses
How do you install the Spec Miner skill?
Download the spec-miner ZIP from the skill's page on this directory and unzip it. You can put the skill folder in one of two places: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want it available only for that project.
If you use the Claude apps instead of files on disk, open Settings, go to Capabilities, then Skills, and upload the ZIP there.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you trigger the skill with a natural request?
You do not need a special command. Describe what you need in plain language and include one of the skill's trigger phrases where it fits. The skill's description lists these phrases: reverse engineer, old codebase, no docs, no documentation, figure out how this works, inherited project, legacy analysis, code archaeology, and undocumented features.
Be specific about scope. Asking about the whole system is different from asking about one feature, and the skill's first step is to decide which boundary applies.
- 'Reverse engineer the billing module in this repo and write a spec.'
- 'This is an inherited project with no docs. Figure out how the login flow works.'
- 'Generate API documentation from the source for the routes in src/api.'
- 'Create architecture documentation from the implementation, focusing on how data is stored.'
What should you expect in the output, and what to check?
The skill saves its report as specs/{project_name}_reverse_spec.md. The template asks for the technology stack and architecture, module structure, observed requirements in EARS format, non-functional observations, inferred acceptance criteria, uncertainties and questions, and recommendations.
Treat the report as a draft for human review. The skill's own documentation says the output is inferred from code and can miss intent or runtime behaviour. Check the uncertainties section first, and verify important claims against the code locations it cites.
- Observed facts should be separated from inferences; check which is which
- Each observation should point to code locations you can open and verify
- Review the uncertainties section before relying on any requirement
specs/{project_name}_reverse_spec.mdWhat does the skill need, and what are the safety notes?
The skill's listing states it requires nothing beyond the tools it uses. It does not run scripts and does not use the network. Its allowed tools are Read, Grep and Glob, so the agent reads and searches your files but the skill itself is not described as executing code.
The main privacy consideration is that the agent reads the source code directly. If you cannot share the codebase with an AI tool, do not use this skill on it. Also be aware that the skill explicitly says it does not skip security pattern analysis, but its output is still a draft and not a security audit.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Allowed tools: Read, Grep, Glob
- Do not use on code you are not permitted to share with an AI tool
What commands does the agent use to explore the code?
The skill includes example search patterns the agent can run with Glob and Grep. They are useful to read so you know what the agent will look for. They include entry points, technical debt markers, configuration usage and API route definitions.
The skill's checklist also covers authentication, validation, error handling, external calls, configuration, tests and background jobs. Test files are treated as a source of observed behaviour.
- Entry points: Glob('**/*.py', exclude=['**/test*', '**/__pycache__/**'])
- Technical debt markers: Grep('TODO|FIXME|HACK|XXX', include='*.py')
- Configuration: Grep('os\.environ|config\[|settings\.', include='*.py')
Grep('@app\.route|@router\.|router\.get|router\.post', include='*.py')What people use it for
- Taking over an inherited project and getting a first map of its modules, routes and data models
- Generating API documentation from route definitions in source code
- Understanding the current behaviour of a feature before planning a change to it
- Creating architecture documentation from the implementation when none exists
Frequently asked questions
How do I install the spec-miner skill?
Download the spec-miner ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings, Capabilities, then Skills.
Does the spec-miner skill need any requirements or extra software?
The skill's listing states that it requires nothing. It does not run scripts and does not use the network. Its allowed tools are Read, Grep and Glob.
Is the spec-miner skill free to use?
The skill is licensed under MIT, as stated in its listing. This page does not describe any pricing, so check the source repository for the licence terms that apply to your use.
Can spec-miner replace documentation for a project I already document well?
Not really. The skill only reflects what the code does, not what it should do. If you already have good documentation or a formal requirements source, the skill is not the best fit.
Why does the output include uncertainties?
The skill's output is inferred from source code and can miss intent or runtime behaviour. Uncertainties are listed separately so a human reviewer can resolve them before relying on the spec.
What should I do if the agent produces an incomplete spec?
Ask the agent to continue exploring. The skill's checkpoint says that if key entry points, configuration files or core modules are unread, exploration should continue before documentation is written. You can also narrow the scope to one feature.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Spec Miner suits developers taking over a legacy or undocumented codebase, and teams who want API or architecture documentation drafted from source. It is a poor fit for projects with good existing documentation, for code you cannot share with an AI tool, or for anyone who expects a verified, complete spec without human review.
Download the skill