Code Pattern Extraction Skill Skill

Code Pattern Extraction Skill

You are an expert software architect specializing in extracting reusable patterns from codebases. Your goal is to transform working implementations into comprehensive Skills that can be applied to new projects.

Core Philosophy

Patterns are transferable knowledge - they capture not just what code does, but why it works, when to use it, and how to adapt it. A good pattern extraction:

Abstracts the essence while preserving critical details
Documents the context in which the pattern applies
Provides concrete examples from the source implementation
Identifies edge cases and common pitfalls
Includes testing strategies to verify correct implementation

Agent Skills Format Specification

This section defines the official Agent Skills format. All extracted patterns MUST follow this specification.

Directory Structure

A skill is a folder containing at minimum a SKILL.md file:

skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: additional documentation
└── assets/           # Optional: templates, images, data files

SKILL.md Format

The SKILL.md file MUST contain YAML frontmatter followed by Markdown content.

Required Frontmatter

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Optional Frontmatter

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Requires pdfplumber, pypdf. No network access needed.
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Read Edit
---

Frontmatter Field Specifications

`name` Field (Required)

| Constraint | Requirement | |------------|-------------| | Length | 1-64 characters | | Characters | Lowercase letters (a-z), numbers (0-9), and hyphens (-) only | | Hyphens | Cannot start or end with hyphen; no consecutive hyphens (--) | | Directory | Must match the parent directory name |

Valid: pdf-processing, data-analysis, oauth-credential-injection Invalid: PDF-Processing (uppercase), -pdf (starts with hyphen), pdf_processing (underscore)

`description` Field (Required)

| Constraint | Requirement | |------------|-------------| | Length | 1-1024 characters | | Content | Must describe BOTH what the skill does AND when to use it | | Keywords | Include specific terms that help agents identify relevant tasks |

Good Example:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Poor Example:

description: Helps with PDFs.

Optional Fields

| Field | Constraints | Example | |-------|-------------|---------| | license | License name or file reference | MIT, Apache-2.0 | | compatibility | Max 500 chars, environment requirements | Requires git, docker | | metadata | Key-value mapping | author: org, version: "1.0" | | allowed-tools | Space-delimited tool list (experimental) | Bash(git:*) Read Edit |

Optional Directories

scripts/

Contains executable code that agents can run:

Should be self-contained or clearly document dependencies
Include helpful error messages
Handle edge cases gracefully
Common languages: Python, Bash, JavaScript

references/

Contains additional documentation loaded on demand:

REFERENCE.md - Detailed technical reference
Domain-specific files (finance.md, legal.md, etc.)
Keep files focused; smaller files = less context usage

assets/

Contains static resources:

Templates (document templates, configuration templates)
Images (diagrams, examples)
Data files (lookup tables, schemas)

Progressive Disclosure

Skills use progressive disclosure to manage context efficiently:

| Level | Content | Token Budget | When Loaded | |-------|---------|--------------|-------------| | Metadata | name and description | ~100 tokens per skill | At startup | | Instructions | Full SKILL.md body | <5000 tokens recommended | When skill is activated | | Resources | Files in scripts/, references/, assets/ | As needed | Only when required |

Guidelines:

Keep SKILL.md under 500 lines
Move detailed reference material to separate files
Keep file references one level deep from SKILL.md
Avoid deeply nested reference chains

File References

Use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Pattern Extraction Workflow

Phase 1: Deep Analysis

Before extracting any patterns, perform comprehensive analysis:

1. Code Exploration

1. Identify the feature's entry points (controllers, services, commands)
2. Trace the data flow through the system
3. Map the class/module relationships
4. Note the dependencies and their roles
5. Identify configuration points (YAML, environment, database)

2. Documentation Review

1. Read feature specs in docs/features/
2. Review JTBD (Jobs To Be Done) playbooks in docs/jtbd/
3. Check blog posts for debugging insights in docs/blog/
4. Review manual test documentation in docs/manual-tests/
5. Examine any walkthroughs in docs/walkthroughs/

3. Test Analysis

1. Review test files to understand expected behaviors
2. Note edge cases covered by tests
3. Identify testing patterns specific to this feature
4. Document integration/system test strategies

Phase 2: Pattern Identification

Categorize the patterns you find:

Structural Patterns

Model relationships and associations
Inheritance hierarchies (STI, polymorphism)
Module composition and concerns
Service object organization

Behavioral Patterns

Data flow and transformations
Event handling and callbacks
Error handling strategies
Async processing patterns

Integration Patterns

External API communication
Authentication/authorization flows
Configuration injection
Credential management

UI/UX Patterns

Controller conventions
View organization
JavaScript/Stimulus patterns
Form handling

Testing Patterns

Factory strategies
Mock/stub approaches
System test synchronization
Integration test isolation

Phase 3: Skill Creation

For each significant pattern, create a Skill following the official format.

Complete Skill Template

---
name: pattern-name-here
description: Concise description of what this pattern does and when to use it. Include keywords that help agents identify relevant tasks.
license: MIT
metadata:
  author: your-org
  version: "1.0"
---

# Pattern Name

## Problem Statement
What problem does this pattern solve? (2-3 sentences)

## When to Use
- Specific scenario where this pattern applies
- Another indicator that this pattern is relevant
- Keywords: [terms someone might search for]

## Core Concept
Brief explanation of the pattern's essence. Focus on the "why" not just the "what". (2-3 sentences max)

## Implementation Guide

### Key Components
| File/Class | Role |
|------------|------|
| `app/models/foo.rb` | Main model implementing X |
| `app/services/bar_service.rb` | Orchestrates Y |

### Step-by-Step Implementation

#### Step 1: Create the base model
```ruby
# app/models/foo.rb
class Foo < ApplicationRecord
  # Example code from the source implementation
end

Step 2: Add the service layer

# app/services/bar_service.rb
class BarService
  # Continue with implementation...
end

Configuration

# config/settings.yml
feature:
  enabled: true
  option: value

Integration Points

Connects to X via Y
Depends on Z being configured

Testing Strategy

Unit Tests

RSpec.describe Foo do
  it "does the thing" do
    # Test example
  end
end

Integration Tests

How to test the pattern works end-to-end.

Common Test Pitfalls

Watch out for X when testing
Remember to mock Y

Common Pitfalls

Pitfall Name: Description and how to avoid it
Another Pitfall: What goes wrong and the fix

Variations

Variation Name

When to use this variation and how it differs from the base pattern.

Debugging Tips

Check X when you see error Y
Use rails console to verify Z

Related Patterns

related-pattern-name - Often used together
alternative-pattern - Use when conditions differ


### Phase 4: Skill Organization

Save extracted Skills to `.claude/skills/` with directory names matching the skill name:

.claude/skills/ ├── oauth-credential-injection/ │ ├── SKILL.md │ └── references/ │ └── oauth-providers.md ├── mcp-server-integration/ │ ├── SKILL.md │ └── scripts/ │ └── validate-server.py ├── multi-tenant-data-access/ │ └── SKILL.md └── rails-controller-testing/ ├── SKILL.md └── references/ └── authentication-helpers.md


---

## Quality Checklist

Before finalizing any Skill, verify:

### Format Compliance
- [ ] `name` is lowercase with hyphens only (no underscores, no uppercase)
- [ ] `name` matches the parent directory name
- [ ] `name` is 1-64 characters, doesn't start/end with hyphen
- [ ] `description` is 1-1024 characters
- [ ] `description` describes both WHAT and WHEN to use
- [ ] SKILL.md is under 500 lines
- [ ] File references are relative and one level deep

### Content Quality
- [ ] **Transferable**: Can be applied to a completely new project
- [ ] **Self-Contained**: All necessary context is included
- [ ] **Actionable**: Clear steps to implement
- [ ] **Tested**: Testing strategy is documented
- [ ] **Edge Cases**: Common pitfalls are documented
- [ ] **Concrete**: Includes real code examples
- [ ] **Concise**: No unnecessary explanation (Claude is smart)

---

## Example Pattern Categories

Common patterns to look for:

| Category | Examples |
|----------|----------|
| **Auth** | OAuth injection, multi-tenant isolation, RBAC |
| **LLM/AI** | Client abstraction, provider switching, streaming, tool calling |
| **External Services** | API clients, webhooks, retry/backoff |
| **Data Modeling** | STI, polymorphic associations, JSONB config |
| **Background Jobs** | Idempotency, error handling, progress tracking |
| **Testing** | Factory patterns, auth helpers, system test sync |

---

## Output Format

When extracting patterns, provide:

1. **Summary**: Brief overview of patterns found
2. **Pattern Skills**: Complete SKILL.md files for each pattern (following the spec above)
3. **Organization**: Suggested directory structure
4. **Dependencies**: Any patterns that depend on others

## Utility Scripts

This skill includes helper scripts for creating and validating skills:

### Initialize a New Skill

```bash
python scripts/init_skill.py <skill-name> --path <output-dir> [--resources scripts,references,assets]

Examples:

python scripts/init_skill.py oauth-injection --path .claude/skills
python scripts/init_skill.py mcp-integration --path .claude/skills --resources scripts,references

Validate and Package a Skill

python scripts/package_skill.py <path/to/skill> [output-dir]
python scripts/package_skill.py .claude/skills/my-skill --validate-only

The packager validates name format, description quality, and directory structure before creating a .skill file.

Reference Guides

For detailed patterns, see:

Workflow Patterns - Sequential, conditional, iterative, and validation workflows
Output Patterns - Templates, code examples, documentation patterns

What NOT to Include in Skills

A skill should only contain essential files. Do NOT create:

| File | Why Not | |------|---------| | README.md | Put everything in SKILL.md | | CHANGELOG.md | Use metadata.version if needed | | INSTALLATION_GUIDE.md | Skills aren't installed by users | | CONTRIBUTING.md | Skills are self-contained | | QUICK_REFERENCE.md | Use references/ directory instead |

Content Anti-Patterns:

❌ Excessive explanation - Claude is smart, be concise
❌ Vague descriptions - Be specific about triggers
❌ Missing "when to use" - Always include trigger conditions
❌ Deeply nested references - Keep one level deep
❌ Duplicate information - Single source of truth

Iteration Workflow

After creating a skill, iterate based on real usage:

Use the skill on real tasks
Notice struggles or inefficiencies
Identify how SKILL.md or resources should be updated
Implement changes
Validate with package_skill.py --validate-only
Test again on similar tasks

Important Notes

Follow the spec exactly - name format, description length, directory structure
Focus on patterns that are truly reusable - not just implementation details
Include enough context that Claude could reimplement in a new project
Don't over-abstract - concrete examples are valuable
Consider variations of the pattern for different scenarios
Always include testing strategies - untestable patterns are incomplete
Keep SKILL.md under 500 lines - use references/ for additional detail

Agent Skills: Code Pattern Extraction Skill

Install this agent skill to your local

Skill Files