Documentation > Tutorials > Pattern Discovery Workflow

Guide ID	T-9
Audience	Developers
Prerequisites	GS-3: How It Works
Time	15 minutes
Difficulty	Intermediate

Pattern Discovery Workflow

The discover command is the most powerful feature in GSD Skill Creator for finding recurring patterns across all your Claude Code sessions and projects. Instead of waiting for the suggestion system to detect patterns in a single project, discovery scans your entire session history, extracts tool sequences and prompt clusters, ranks candidates by relevance, and generates draft skills for the patterns you select. This tutorial walks through the complete pipeline.

What Discover Does

The discovery pipeline runs six stages:

• Scan — Enumerates all projects under ~/.claude/projects/ and stream-parses JSONL session files. Handles large files (23MB+) without loading them entirely into memory.
• Extract — Identifies tool sequence n-grams (bigrams like Read followed by Edit, trigrams like Read followed by Edit followed by Bash) and classifies Bash commands into 8 categories: git, build, test, install, search, file-ops, docker, and other.
• Cluster — Groups similar user prompts using DBSCAN (density-based clustering) with automatic epsilon tuning via k-NN knee detection. Clusters per-project first, then merges across projects.
• Rank — Scores all candidates using a multi-factor formula that considers frequency, cross-project occurrence, recency, and consistency. Deduplicates against existing skills so you are not shown patterns you have already captured.
• Present — Displays ranked tool pattern candidates and cluster candidates with evidence showing which sessions and projects the pattern appeared in, along with specific examples.
• Draft — Generates SKILL.md files for the candidates you select, with pre-filled workflow steps based on the detected pattern.

Step 1: Run Discovery

Launch the full discovery pipeline:

skill-creator discover

The command displays progress during scanning: project count, session count, and patterns found. The first run scans all sessions and may take 30-60 seconds for large session histories. Subsequent runs are fast because discovery uses incremental scanning via watermarks — only new or modified sessions are processed.

Options for controlling the scan:

# Exclude a specific project from scanning
skill-creator discover --exclude my-private-project

# Force full rescan (reprocess all sessions, ignore watermarks)
skill-creator discover --rescan

# Combine options
skill-creator discover --rescan --exclude scratch-project

Step 2: Review Ranked Candidates

The discovery output presents two types of candidates:

Tool Pattern Candidates

Recurring tool sequences detected across sessions. Each candidate shows the tool sequence (e.g., "Read, Edit, Bash"), the number of occurrences, which projects it appeared in, and example commands. These represent workflow patterns that repeat — the kinds of actions you perform in a consistent order.

Prompt Cluster Candidates

Semantically similar user prompts grouped by intent. Each cluster shows example prompts, the number of sessions containing similar prompts, and cross-project occurrence. These represent recurring intents — questions or requests you make repeatedly in similar ways.

For each candidate, the ranking score reflects:

• Frequency — How often the pattern occurs
• Cross-project occurrence — Patterns appearing in multiple projects rank higher
• Recency — Recent patterns rank higher than old ones
• Consistency — Patterns that occur regularly rank higher than sporadic ones

Step 3: Select Candidates to Draft

For each table, you can interactively select which candidates to turn into draft skills. The selection UI lets you browse candidates and choose the ones worth capturing as skills.

Selected candidates generate SKILL.md files in .claude/skills/ with pre-filled content based on the detected pattern. The generated skills include appropriate trigger keywords, description text, and workflow steps derived from the evidence.

Key Features

Incremental Scanning

After the initial scan, discovery uses watermarks stored at ~/.gsd-skill-creator/discovery/scan-state.json to track which sessions have been processed. On subsequent runs, only new or modified sessions are scanned. This makes regular discovery fast — typically completing in seconds rather than minutes.

Noise Filtering

Framework patterns — tool sequences that appear in 15 or more projects and in 80% or more of tracked projects — are automatically filtered as noise. These are patterns inherent to using Claude Code itself (like Read followed by Edit) rather than patterns specific to your workflow.

Deduplication

Patterns that match existing skills in your library are automatically skipped. You will not be shown candidates for patterns you have already captured, keeping the discovery output focused on genuinely new opportunities.

Stream Parsing

Session files are parsed as streams, not loaded entirely into memory. This allows discovery to handle large session files (23MB+) without excessive memory usage.

What's Next

• How It Works — Review the six-step workflow that discovery feeds into
• Creating Your First Skill — Validate and test the draft skills generated by discovery