Index of every page on this site: llms.txt
All skills
jeffallan avatar

/spec-miner

@67c1961
by jeffallanjeffallan/claude-skills12k stars
1,202
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/jeffallan/claude-skills/spec-miner

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈147 tokens for metadata: the name and description. ≈933 when used: this file. ≈1.9k more on demand in 4 files.

Description uses 7.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈587 characters, or 7.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Scope - Identify analysis boundaries (full system or specific feature)
  2. 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.
  3. Trace - Follow data flows and request paths
  4. Document - Write observed requirements in EARS format
  5. 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:

  1. Technology stack and architecture
  2. Module/directory structure
  3. Observed requirements (EARS format)
  4. Non-functional observations
  5. Inferred acceptance criteria
  6. Uncertainties and questions
  7. Recommendations

Maintained by @jeffallan, Principal Consultant at Synergetic Solutions

Documentation

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert23d5 checks · Risk CRITICAL
  • Gen Agent Trust Hub23d

    The skill is designed to analyze codebases for sensitive information but references a documentation website that has been flagged as malicious by automated security scanners. It also lacks adequate boundaries when processing untrusted code, creating a risk for indirect prompt injection.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

  • Runlayer8mo

    1/5 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 67c1961. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 3 weeks ago
All 1 allowed tools
Read Grep Glob
Other metadata
metadata
{
  "author": "https://github.com/Jeffallan",
  "company": "https://synergetic.solutions",
  "version": "1.1.0",
  "domain": "workflow",
  "triggers": "reverse engineer, legacy code, code analysis, undocumented, understand codebase, existing system",
  "role": "specialist",
  "scope": "review",
  "output-format": "document",
  "related-skills": "feature-forge, fullstack-guardian, architecture-designer"
}
  • Documentation
  • reverse-engineering
  • legacy-code
  • code-analysis
  • codebase-exploration
  • requirements-extraction
  • architecture
  • undocumented-systems

README badge

README badge for jeffallan/claude-skills/spec-miner

Extracts specifications from undocumented or legacy codebases by systematically exploring code structure, tracing data flows, and documenting observed behavior in EARS format. Use this skill when onboarding to inherited projects, creating documentation from implementation, or understanding systems with no written specification.

Generated from the current SKILL.md.

What tools can this skill use to explore a codebase?
The skill uses Read, Grep, Glob, and Bash to map file structure, locate patterns, trace data flows, and extract observable behaviors from source code.
Does this skill generate documentation in a specific format?
Yes. It documents observed requirements using EARS (Easy Approach to Requirements Syntax) format, which structures behavior as ubiquitous, event-driven, state-driven, or optional rules.
Can this skill work on any codebase or language?
The skill is language-agnostic and designed for any codebase, but examples in the documentation focus on Python (Flask, Django) and Express. Adjustment of Glob and Grep patterns may be needed for other languages or frameworks.
Does this skill make assumptions or only report what it finds in code?
The skill must ground all observations in actual code evidence and distinguish between observed facts and inferences. It documents uncertainties in a dedicated section rather than making unsupported assumptions.
What does the skill output?
It produces a specification document saved as `specs/{project_name}_reverse_spec.md`, including technology stack, module structure, observed requirements, non-functional observations, inferred acceptance criteria, uncertainties, and recommendations.

Generated from the current SKILL.md. These answers refresh after source changes.