Structured Data
Capability Metadata
| Field | Value |
|---|---|
| ID | CAP-002 |
| Version | v1.0 |
| Domain | Core Learning |
| Status | Documented |
| Related | CAP-001, CAP-003, CAP-010 |
| Source | src/suggestion/skill-suggester.ts |
| Toggle | suggest_skills (integration.json) |
Configuration Reference
Toggle: suggest_skills in integration.json
{
"suggest_skills": true,
"suggestion_threshold": 3
}Threshold: 3 occurrences of a pattern before suggestion fires
Command: /sc:suggest — interactive suggestion review
Technical Specifications
Class: SkillSuggester
// Suggestion record produced by SkillSuggester
interface SuggestionRecord {
pattern_id: string; // Links to sessions.jsonl hash
confidence: number; // 0.0 to 1.0
evidence: string[]; // Session IDs that triggered
draft_skill: string; // Generated markdown content
created_at: string; // ISO 8601 UTC
}
class SkillSuggester {
analyze(sessions: ObservationRecord[]): SuggestionRecord[];
getSuggestions(): SuggestionRecord[];
dismiss(pattern_id: string): void;
}Output: Pending suggestions listed in /sc:suggest output
Overview
After observation accumulates data, the system needs a trigger to act on it. Suggesting Skills is that trigger. It watches the accumulated patterns from Capturing Patterns (CAP-001) and fires when a pattern's occurrence count crosses the 3-occurrence threshold — the signal-to-noise cutoff that separates genuine habits from one-off coincidences.
A suggestion is not a command — it is a proposal. When the system suggests a skill, it generates a draft skill file with a description of the pattern, the evidence sessions that triggered it, and a skeleton implementation. That draft is surfaced to you through the /sc:suggest command or as a session-start notification. You review it, modify it, and decide whether to create it. Nothing is written to your skill library without your explicit approval.
This design — observe, detect, propose, wait — is the core philosophy of the bounded learning system. The machine notices; the human decides. Suggesting Skills is the propose-and-wait step that makes the learning loop safe to run autonomously.
History
Suggesting Skills shipped alongside Capturing Patterns in v1.0 as the second step of the original learning loop. From the beginning, the 3-occurrence threshold was a deliberate design choice. One occurrence proves nothing — it could be an experiment. Two is interesting but ambiguous. Three, across different sessions, is the minimum that distinguishes a genuine habit from noise. This threshold has never been changed in the core; it is available as a configuration option but 3 remains the default.
The interactive review mechanism — the /sc:suggest command — was formalized in v1.11. Prior to v1.11, suggestions appeared only as session-start notifications with no structured review flow. The v1.11 command introduced the ability to view pending suggestions, inspect the evidence, preview the draft skill, and accept or dismiss each one in a single interactive pass. This significantly improved the user experience for projects with many accumulated suggestions.
Key Concepts
Think of it like a study buddy who notices "you always look up that formula before calculating" and suggests you write it on an index card. The system notices patterns in your work and suggests you make them reusable — but you always approve before anything happens.
The study buddy has a rule: they won't suggest something until they've seen you do it at least three times. Once is a fluke. Twice is interesting. Three times means it's worth capturing. That's the 3-occurrence threshold — it filters out coincidences and surfaces only real, repeated behavior.
When a suggestion appears, you'll see exactly which sessions triggered it — the "evidence." You can look at those sessions, decide whether the pattern is real and worth capturing, and either approve the suggested skill or dismiss it. The system never creates a skill without your say-so.
Usage Examples
Example 1: Review pending skill suggestions
# Inside a Claude Code session, run the suggest command
/sc:suggest
# Output shows pending suggestions:
# [1] Pattern: read-edit-test-commit (confidence: 0.87)
# Evidence: sessions a1b2c, f3d4e, 9g8h7
# Draft: "TDD workflow — Read test file, edit source, run tests, commit"
# Accept? [y/n/preview]Example 2: Preview a draft skill before accepting
# When reviewing a suggestion, enter 'preview' to see the draft
Accept? [y/n/preview] preview
# Shows the generated skill markdown:
# ---
# name: tdd-workflow
# description: Read test file, edit source, run tests, commit
# triggers: ["test", "edit", "failing"]
# ---
# When working on tests: Read the test file first, then edit
# the implementation, run tests to verify, then commit.Example 3: Configure suggestion threshold
// integration.json — increase threshold for less noise
{
"suggest_skills": true,
"suggestion_threshold": 5 // require 5 occurrences instead of 3
}