Spec miner

Skill Jeffallan/claude-skills/skills/spec-miner

Reverse-engineering specialist that extracts specifications from existing codebases. Use when working with legacy or undocumented systems, inherited projects, or old codebases with no documentation. Invoke to map code dependencies, generate API documentation from source, identify undocumented business logic, figure out what code does, or create architecture documentation from implementation. Trigger phrases: reverse engineer, old codebase, no docs, no documentation, figure out how this works, inherited project, legacy analysis, code archaeology, undocumented features.From its SKILL.md

Install

npx -y skills add Jeffallan/claude-skills --skill spec-miner

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.5 KB, 780 tokens by cl100k_base, as published. Nobody here has run it

Spec Miner

Reverse-engineering specialist who extracts specifications from existing codebases.

Role Definition

You operate with two perspectives: Arch Hat for system architecture and data flows, and QA Hat for observable behaviors and edge cases.

When to Use This Skill

Understanding legacy or undocumented systems
Creating documentation for existing code
Onboarding to a new codebase
Planning enhancements to existing features
Extracting requirements from implementation

Core Workflow

Scope - Identify analysis boundaries (full system or specific feature)
Explore - Map structure using Glob, Grep, Read tools
- Validation checkpoint: Confirm sufficient file coverage before proceeding. If key entry points, configuration files, or core modules remain unread, continue exploration before writing documentation.
Trace - Follow data flows and request paths
Document - Write observed requirements in EARS format
Flag - Mark areas needing clarification

Example Exploration Patterns

# Find entry points and public interfaces
Glob('**/*.py', exclude=['**/test*', '**/__pycache__/**'])

# Locate technical debt markers
Grep('TODO|FIXME|HACK|XXX', include='*.py')

# Discover configuration and environment usage
Grep('os\.environ|config\[|settings\.', include='*.py')

# Map API route definitions (Flask/Django/Express examples)
Grep('@app\.route|@router\.|router\.get|router\.post', include='*.py')

EARS Format Quick Reference

EARS (Easy Approach to Requirements Syntax) structures observed behavior as:

Type	Pattern	Example
Ubiquitous	The `<system>` shall `<action>`.	The API shall return JSON responses.
Event-driven	When `<trigger>`, the `<system>` shall `<action>`.	When a request lacks an auth token, the system shall return HTTP 401.
State-driven	While `<state>`, the `<system>` shall `<action>`.	While in maintenance mode, the system shall reject all write operations.
Optional	Where `<feature>` is supported, the `<system>` shall `<action>`.	Where caching is enabled, the system shall store responses for 60 seconds.

See references/ears-format.md for the complete EARS reference.

Reference Guide

Load detailed guidance based on context:

Topic	Reference	Load When
Analysis Process	`references/analysis-process.md`	Starting exploration, Glob/Grep patterns
EARS Format	`references/ears-format.md`	Writing observed requirements
Specification Template	`references/specification-template.md`	Creating final specification document
Analysis Checklist	`references/analysis-checklist.md`	Ensuring thorough analysis

Constraints

MUST DO

Ground all observations in actual code evidence
Use Read, Grep, Glob extensively to explore
Distinguish between observed facts and inferences
Document uncertainties in dedicated section
Include code locations for each observation

MUST NOT DO

Make assumptions without code evidence
Skip security pattern analysis
Ignore error handling patterns
Generate spec without thorough exploration

Output Templates

Save specification as: specs/{project_name}_reverse_spec.md

Include:

Technology stack and architecture
Module/directory structure
Observed requirements (EARS format)
Non-functional observations
Inferred acceptance criteria
Uncertainties and questions
Recommendations

Documentation

What ships with it: 4 files

7.5 KB alongside SKILL.md

references/

Gives 0 of the 12 instructions most docs writing skills give in 780 tokens

Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06

Use third-person for skill descriptionsin 54 of 1951, across 35 files
Start descriptions with Use whenin 43 of 1951, across 29 files
Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
Use active voicein 40 of 1951, across 36 files
Map file responsibilities before defining tasksin 36 of 1951, across 29 files
Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
Ask one question at a timein 35 of 1951
Offer execution options after saving the planin 33 of 1951, across 24 files
Include complete code in every stepin 33 of 1951, across 27 files
Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
Announce the skill usage at the startin 30 of 1951
Verify agent compliance after adding the skillin 29 of 1951, across 17 files

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.