How Observation Works

Pattern detection in skill-creator begins with passive observation. During every Claude Code session, skill-creator monitors your interactions and records notable events to a structured log. This observation is non-intrusive—it does not slow your workflow or require any explicit action on your part.

Observations are appended to .planning/patterns/sessions.jsonl, a JSON Lines file where each line is a self-contained JSON object representing one observation. The append-only format ensures that observations accumulate over time without risk of data loss from concurrent writes.

# Example session log entries
{"ts":"2026-02-23T10:15:00Z","type":"tool-seq","seq":["grep","read","edit","bash:npm test"],"ctx":"execute-phase 5"}
{"ts":"2026-02-23T10:22:00Z","type":"correction","before":"const x = 5","after":"const x = 5 as const","ctx":"typescript-patterns"}
{"ts":"2026-02-23T10:30:00Z","type":"file-touch","files":["src/index.ts","src/types.ts","tests/index.test.ts"],"ctx":"execute-phase 5"}

What Gets Observed

The observation system captures five categories of session data:

Commands and Tool Sequences

Every tool invocation is recorded in order. When the same sequence of tools appears across sessions, it signals a workflow pattern. For example, if Claude consistently runs grep → read → edit → bash:test → commit when fixing bugs, that five-step sequence becomes a candidate pattern.

File Access Patterns

Which files are read or modified during specific GSD phases. If execute-phase for TypeScript projects always touches src/types.ts, tsconfig.json, and test files, that co-occurrence pattern is recorded.

Tool Sequences After Failures

What happens after a test failure or verification issue is particularly valuable. If Claude consistently runs read test output → grep for error → read source → edit → re-run test after a test failure, that recovery sequence is a high-value pattern.

User Corrections

When you correct Claude's output, the before/after pair is the highest-signal observation available. Corrections reveal the gap between Claude's default behavior and your actual preferences. These corrections feed the bounded learning system for skill refinement.

Phase Outcomes

Whether a GSD phase succeeded, failed, or partially completed, along with what was different about the session. Outcome data helps identify which patterns correlate with success.

When Patterns Become Candidates

Raw observations are not immediately actionable. The pattern detection pipeline requires a minimum of 3 occurrences before an observation is promoted to a candidate pattern. This threshold exists to filter out one-off behaviors from genuine recurring patterns.

Occurrences	Status	Action
1-2	Observed	Logged but not surfaced
3+	Candidate	Available via skill-creator suggest
5+	High confidence	Proactively mentioned at session start
10+	Strong pattern	Flagged as priority for skill creation

The 3-occurrence minimum is a deliberate design choice. Two occurrences could be coincidence. Three occurrences across different sessions strongly suggest an intentional workflow.

N-gram Extraction and DBSCAN Clustering

The pattern detection engine uses two complementary techniques to discover workflow patterns from raw observation data.

N-gram Extraction

Tool sequences are analyzed using n-gram extraction, the same technique used in natural language processing to find common word sequences. For tool sequences, the system extracts overlapping subsequences of length 2 through 6:

# From sequence: grep, read, edit, test, commit
# 2-grams: [grep,read], [read,edit], [edit,test], [test,commit]
# 3-grams: [grep,read,edit], [read,edit,test], [edit,test,commit]
# 4-grams: [grep,read,edit,test], [read,edit,test,commit]
# 5-gram:  [grep,read,edit,test,commit]

When the same n-gram appears across multiple sessions, its count increments. N-grams with counts of 3 or higher are promoted to candidate patterns.

DBSCAN Clustering

For more complex patterns that do not follow exact sequences, DBSCAN (Density-Based Spatial Clustering of Applications with Noise) groups similar observations by proximity in feature space. Observations are characterized by:

• Tool types involved
• File types touched
• GSD phase context
• Time-of-day patterns
• Outcome (success/failure)

DBSCAN identifies dense clusters of similar observations while ignoring outliers. A cluster that spans 3+ sessions becomes a candidate pattern, even if the exact tool sequences vary slightly between instances.

Reviewing Suggestions

skill-creator suggest

When candidate patterns accumulate, you review them with the suggest command. Each suggestion includes:

• Pattern description — human-readable summary of what was detected
• Occurrence count — how many times the pattern appeared
• Session span — over how many sessions the pattern was observed
• Confidence score — probability that this is a genuine workflow pattern
• Proposed skill name — suggested name for the skill if created

For each suggestion, you have three options:

1. Accept — create a skill from this pattern
2. Defer — keep observing; revisit later when more data accumulates
3. Dismiss — this is not a pattern worth capturing; remove from suggestions

Important: Suggestions are never auto-applied. Even in YOLO mode, skill creation requires explicit user confirmation. This is a core safety principle of the bounded learning system.

From Pattern to Skill: The Creation Process

When you accept a suggestion, skill-creator generates a skill file in the standard format:

1. Frontmatter generation — YAML metadata including name, description, triggers (when the skill should activate), scope (project or user level), and version
2. Content generation — the actual instructions Claude should follow when the skill activates, derived from the observed pattern
3. Validation — the generated skill is checked against the skill schema for structural correctness
4. Placement — the skill file is written to .claude/commands/ (project-level) or ~/.claude/commands/ (user-level)

The generated skill is a starting point. You can (and should) review and refine it. The bounded learning system will also refine it over time based on your corrections.

Bounded Learning: How Corrections Drive Refinement

Once a skill is active, skill-creator continues observing how well it performs. When you correct Claude's behavior in an area covered by an active skill, that correction is counted toward the skill's refinement threshold.

Refinement Guardrails

Constraint	Value	Purpose
Minimum corrections before refinement	3	Prevents knee-jerk changes from one-off corrections
Maximum content change per refinement	20%	Prevents a skill from being completely rewritten
Cooldown between refinements	7 days	Allows time to evaluate the impact of each refinement
User confirmation required	Always	No silent changes to your skill library

These constraints are non-negotiable. They exist to prevent the learning system from oscillating (making and undoing the same change) or from drifting far from the original intent of a skill.

The Refinement Cycle

1. Skill activates during a session
2. Claude follows the skill's instructions
3. You correct the output ("Actually, use X instead of Y")
4. Correction is logged against the skill
5. After 3+ corrections of the same type, a refinement is proposed
6. You review and accept/reject the proposed refinement
7. If accepted, the skill is updated (max 20% content change)
8. 7-day cooldown begins before the skill can be refined again

Co-activation Tracking and Agent Composition

When two or more skills consistently activate together in the same session context, skill-creator tracks this as a co-activation. After 5+ co-activations over 7+ days, the system may propose composing those skills into a unified agent.

For example, if the typescript-patterns skill and test-generator skill consistently activate together during execute-phase, skill-creator might propose a typescript-tdd agent that combines both skill sets into a single, coherent instruction set.

Composed agents are stored in .claude/agents/ and follow the same permission model as skills: they require explicit user confirmation before creation and before any refinement.

Privacy: What Is Stored, Where, and How to Control It

Data Locations

Data	Location	Contains
Session observations	.planning/patterns/sessions.jsonl	Tool sequences, file patterns, corrections, outcomes
Project skills	.claude/commands/*.md	Skill definitions with triggers and instructions
User skills	~/.claude/commands/*.md	User-level skills (shared across projects)
Composed agents	.claude/agents/*.md	Multi-skill agent compositions

Privacy Controls

• Gitignore — add .planning/patterns/ to .gitignore for shared repositories. This prevents observation data from being pushed to shared remotes.
• Cross-project isolation — user-level skills (~/.claude/commands/) must not expose project-specific patterns to other projects. Skill-creator enforces this by sanitizing project-specific details from user-level skills.
• Data retention — session logs can be manually cleared by deleting .planning/patterns/sessions.jsonl. Pattern counts reset but active skills are unaffected.
• Observation opt-out — observation can be disabled entirely through .planning/config.json settings.

Security note: The sessions.jsonl file is append-only, which makes it resistant to accidental overwrites but potentially vulnerable to data poisoning if an attacker has write access. Skill-creator validates entries on read and discards malformed lines. Never run skill-creator on untrusted observation data without review.