Spec Miner Guide: Usage, Examples, and Best Practices for Beginners

Feb 14, 2026

Purpose

This post demonstrates how to use the Spec Miner skill in Claude Code to extract and analyze specifications from codebases.

Environment

Claude Code with claude-skills plugin
Working codebase with specifications
Basic familiarity with Claude Code

What is Spec Miner?

Spec Miner is a skill in the claude-skills ecosystem that helps you extract specifications from your codebase. When you need to understand what a system does, what inputs it accepts, or what outputs it produces, Spec Miner analyzes your code and documents these specifications.

I use Spec Miner when I need to:

Document API contracts from implementation code
Extract validation rules from form handlers
Understand data flow through a system
Generate specifications from existing code

There are two main goals:

extract: Pull specifications from code automatically
analyze: Understand relationships between specifications

Installation and Setup

First, install the claude-skills plugin:

npm install -g @jeffallan/claude-skills

Then verify the installation:

claude-skills --version

You should see the version number printed.

Now activate Spec Miner by adding it to your Claude Code configuration. The skill becomes available automatically when claude-skills is installed.

Core Usage Patterns

The Spec Miner skill triggers when you ask Claude to extract specifications from your code. Common trigger phrases include:

“Extract the specification for this component”
“What are the input/output contracts for this module?”
“Generate a spec document from this codebase”
“Analyze the specification for this API endpoint”

Practical Examples

Example 1: Extracting API Specifications

When I have an Express.js API handler, I can extract its specification:

import { Request, Response } from 'express';

export const createUser = async (req: Request, res: Response) => {
  const { email, name, age } = req.body;

  if (!email || !email.includes('@')) {
    return res.status(400).json({ error: 'Invalid email' });
  }

  if (age < 0 || age > 150) {
    return res.status(400).json({ error: 'Invalid age' });
  }

  const user = await User.create({ email, name, age });
  res.status(201).json(user);
};

I ask Claude:

Extract the specification for the createUser endpoint

Spec Miner generates:

POST /api/users

Input:
- email (string, required): Must be valid email format
- name (string, optional): User display name
- age (number, optional): Must be between 0-150

Output:
- 201: User object created successfully
- 400: Validation error with error message

Validation Rules:
- email: required, must contain '@'
- age: optional, range 0-150

Example 2: Database Schema Specifications

For this database model:

import { Sequelize, DataTypes } from 'sequelize';

const Product = sequelize.define('Product', {
  id: {
    type: DataTypes.UUID,
    defaultValue: DataTypes.UUIDV4,
    primaryKey: true
  },
  name: {
    type: DataTypes.STRING(100),
    allowNull: false,
    validate: {
      notEmpty: true
    }
  },
  price: {
    type: DataTypes.DECIMAL(10, 2),
    allowNull: false,
    validate: {
      min: 0
    }
  },
  sku: {
    type: DataTypes.STRING(50),
    unique: true,
    allowNull: false
  }
});

I run:

Extract the database specification for Product model

Spec Miner outputs:

Product Table Schema

Columns:
- id: UUID, primary key, auto-generated
- name: VARCHAR(100), NOT NULL, non-empty
- price: DECIMAL(10,2), NOT NULL, minimum 0
- sku: VARCHAR(50), NOT NULL, UNIQUE

Constraints:
- Primary key: id
- Unique constraint: sku
- Not null: name, price, sku

Validation:
- name: cannot be empty string
- price: must be >= 0

Example 3: Component Interface Specifications

For this React component:

interface UserCardProps {
  user: {
    id: string;
    name: string;
    email?: string;
    avatar?: string;
  };
  onEdit?: (id: string) => void;
  onDelete?: (id: string) => void;
  showActions?: boolean;
}

export const UserCard: React.FC<UserCardProps> = ({
  user,
  onEdit,
  onDelete,
  showActions = true
}) => {
  return (
    <div className="user-card">
      <img src={user.avatar || '/default.png'} alt={user.name} />
      <h3>{user.name}</h3>
      {user.email && <p>{user.email}</p>}
      {showActions && (
        <div>
          {onEdit && <button onClick={() => onEdit(user.id)}>Edit</button>}
          {onDelete && <button onClick={() => onDelete(user.id)}>Delete</button>}
        </div>
      )}
    </div>
  );
};

I ask:

What is the component specification for UserCard?

Spec Miner produces:

UserCard Component Specification

Props:
- user (required): Object
  - id: string
  - name: string
  - email: string (optional)
  - avatar: string (optional)
- onEdit: function(id: string) (optional)
- onDelete: function(id: string) (optional)
- showActions: boolean (optional, default: true)

Behavior:
- Displays user avatar (or default if none provided)
- Shows user name
- Shows email only if provided
- Renders action buttons only when showActions=true
- Edit button appears only when onEdit callback provided
- Delete button appears only when onDelete callback provided

Default Values:
- showActions: true
- avatar: '/default.png' (fallback)

Best Practices

DO: Use Spec Miner When

You’re documenting existing code
Onboarding to a new codebase
Creating API documentation
Building contract tests
Understanding data validation rules
Preparing for refactoring

DO: Follow These Patterns

Extract before refactoring: Get specs first, then change code
Document edge cases: Spec Miner captures validation rules
Version your specs: Save output to track changes over time
Cross-reference: Compare extracted specs with existing docs

DON’T: Common Mistakes

Don’t assume specs are complete: Extracted specs capture implementation, not intent
Don’t skip manual review: Always verify extracted specifications
Don’t ignore business logic: Some rules may be implicit
Don’t extract once: Re-run when code changes

DON’T: Use Spec Miner For

Writing specifications from scratch (it extracts, doesn’t create)
Replacing documentation (use it to augment docs)
Understanding architecture (use other skills for system design)
Performance profiling (not a profiling tool)

How Spec Miner Fits In

The claude-skills ecosystem includes several related skills:

skill-creator: Build new skills from patterns
architect: System design and architecture decisions
tdd-guide: Test-driven development workflow
security-review: Security analysis of code

Spec Miner works well with these. For example, I use skill-creator after extracting specs to build a new skill, or security-review to validate that extracted specs don’t have security issues.

Summary

In this post, I showed how to use Spec Miner skill in Claude Code to extract specifications from TypeScript code. The key point is that Spec Miner helps you understand what your code does by documenting input contracts, output formats, and validation rules.

I demonstrated extracting specs from API endpoints, database models, and React components. The skill works by analyzing your code and generating structured documentation about interfaces, contracts, and validation rules.

You can see that Spec Miner is most useful when you need to document existing code, understand a new codebase, or prepare for refactoring.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 claude-skills Documentation
👨‍💻 claude-skills GitHub Repository

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!