distill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Distill Skill

## The Insight

Sessions are rich with implicit knowledge — recurring corrections, repeated preferences, workflow adjustments — that evaporates when the session ends. This skill captures those patterns and crystallizes them into durable project documentation (CLAUDE.md, AGENTS.md, etc.) so future sessions start smarter.

**The difference from /learner:**
- **learner**: Extracts a single, specific technical skill from a debugging breakthrough → saves as a reusable `.md` skill file
- **distill**: Scans the ENTIRE session for behavioral patterns, preferences, and recurring adjustments → updates project documentation files (CLAUDE.md, AGENTS.md)

## Why This Matters

Without distillation, the same corrections repeat session after session:
- "I told you to use Korean" — should be a CLAUDE.md rule
- "Always run tests before committing" — should be a documented convention
- "Don't touch the legacy module" — should be an AGENTS.md boundary
- "Use pnpm, not npm" — should be a build convention

The cost of NOT distilling: users waste time re-explaining preferences that should be permanent rules.

## Recognition Pattern

Use /pepcode:distill when:
- A session involved multiple corrections or preference expressions
- The user repeatedly adjusted Claude's behavior during the session
- New workflow patterns or conventions emerged during development
- The user says "remember this", "always do X", "from now on", "update the rules"
- After a significant project setup or architectural decision session
- At the end of a productive session where conventions were established

Do NOT use when:
- The session was a simple one-off task with no reusable patterns
- The pattern is a technical debugging insight (use /learner instead)
- The change is temporary or experimental

## The Approach

### Step 1: Session Analysis

Scan the entire conversation for these signal categories:

**A. Explicit Directives** (highest priority)
- Direct instructions: "always", "never", "from now on", "remember to"
- Corrections: "no, do it this way", "I meant...", "not like that"
- Preferences: "I prefer", "use X instead of Y", "the convention is"

**B. Implicit Patterns** (medium priority)
- Repeated adjustments (user corrected the same thing 2+ times)
- Consistent choices (user always picked option A over B)
- Workflow sequences that emerged naturally

**C. Architectural Decisions** (captured as context)
- Technology choices made during the session
- Module boundaries established
- Naming conventions agreed upon
- Testing strategies adopted

### Step 2: Categorize & Target

Map each discovered pattern to the right documentation file:

| Pattern Type | Target File | Section |
|---|---|---|
| Language/tone preferences | `CLAUDE.md` | Custom Rules |
| Build/tooling conventions | `CLAUDE.md` | Project Rules or build section |
| Code style/conventions | `CLAUDE.md` | Conventions |
| Agent behavior rules | `CLAUDE.md` | Agent-specific rules |
| Module boundaries | `AGENTS.md` | Module docs |
| File ownership/responsibilities | `AGENTS.md` | Directory docs |
| Architecture decisions | `AGENTS.md` or `CLAUDE.md` | Architecture section |
| Workflow/process rules | `CLAUDE.md` | Workflow section |
| Testing policies | `CLAUDE.md` | Testing section |

### Step 3: Draft Updates

For each target file:

1. **Read the current file** to understand existing structure and avoid duplicates
2. **Check for conflicts** with existing rules — update rather than duplicate
3. **Draft additions** in the file's existing style and format
4. **Preserve existing content** — only add or refine, never remove unless explicitly asked

Rule writing guidelines:
- Be specific and actionable: "Use pnpm for package management" not "Consider using pnpm"
- Include the WHY when non-obvious: "Use UTC timestamps in logs (production servers span multiple timezones)"
- Use imperative tone consistent with existing rules
- Group related rules under meaningful headings
- Keep rules concise — one rule per line when possible

### Step 4: Present & Apply

1. **Show the user a summary** of all discovered patterns with their proposed target files
2. **Present each update as a diff-like preview** so the user can approve/reject individual changes
3. **Ask for confirmation** before writing any files
4. **Apply approved changes** to the target files
5. **Report what was updated** with file paths and line references

### Important Constraints

- **Never remove existing rules** unless the user explicitly asks to replace them
- **Merge with existing sections** rather than creating redundant new sections
- **Respect file structure** — follow the existing formatting, heading levels, and organization
- **CLAUDE.md changes go in the project CLAUDE.md** by default (not user-level ~/.claude/CLAUDE.md), unless the pattern is truly cross-project
- **Cross-project patterns** (e.g., language preference, general coding style) should target `~/.claude/CLAUDE.md` — confirm with user first
- **AGENTS.md updates** should follow the existing hierarchical structure if one exists; create one using deepinit patterns if not

## Example Session Patterns → Rules

**Session pattern**: User corrected Claude 3 times to write commit messages in Korean
```markdown
# → CLAUDE.md addition:
<commit_convention>
커밋 메시지는 항상 한국어로 작성한다. 접두사 `[CP0-11]` 를 사용한다.
</commit_convention>
```

**Session pattern**: User always asked to run `npm run build` after version changes
```markdown
# → CLAUDE.md addition:

From leejaedus/pepcode, MIT.

More from leejaedus/pepcode