How do I install the Distill Skill skill?

Run npx skillmds@latest add digital-stoic-org/distill-skill in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Distill Skill safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Distill Skill?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Distill Skill free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Distill Skill?

digital-stoic-org (@digital-stoic-org) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Distill Skill by digital-stoic-org — Agent Skill

Name: Distill Skill
Rating: 4.666666666666667 (3 reviews)
Author: digital-stoic-org

Distill Skill

Record an interactive Claude Code session and distill it into one or more generalized skills. Captures turns, tool calls, failures, friction, and confusion signals, then hands a structured draft to edit-tool. Use when "distill skill", "record macro", "turn this session into a skill", "extract skill from session", or "/distill-skill [start|finalize]".

File contents

Distill Skill — Session → Skill

Record a CC session, then distill it into a generalized skill via edit-tool. Two modes: forward (record as we go) and retrospective (parse session-so-far).

Modes

Arg	Mode	When
`start`	Forward	User invokes at/near session start. Creates trace dir, annotates turns going forward.
`finalize`	Close out	End of session. Run search-skill dedup, propose split, hand to edit-tool.
`status`	Inspect	Show current trace dir + turn count + friction/confusion tally.
(none)	Retrospective	Parse session-so-far. ⚠️ Warn if compaction may have occurred (turn count high / early context lost).

Workflow

1. `start` — initialize trace

: "${PRAXIS_DIR:?PRAXIS_DIR must be set}"
SID=$(date -Iseconds | tr ':+' '-')
DIR="$PRAXIS_DIR/.tmp/distill-skill/$SID"
mkdir -p "$DIR"
echo "$DIR" > "$PRAXIS_DIR/.tmp/distill-skill/.current"

Create three files in $DIR:

trace.jsonl — append-only per-turn: {ts, turn, user_intent, tools_used, files_touched, outcome, friction?, confusion_flag?}
draft.yaml — RISEN-lite scaffold (see reference.md)
anti-patterns.md — what didn't work + why

Respond: 🎬 Recording to $DIR. Annotate turns as you go. /distill-skill finalize when done.

2. Annotate each turn

After each meaningful turn, append to trace.jsonl — fields: user_intent (generalized, not verbatim) · tools_used · files_touched · outcome ∈ {ok,retry,abandoned} · friction (verbatim correction, if any) · confusion_flag (true if assistant asked clarifying Q → signals upfront disambiguation needed).

Keep draft.yaml filled progressively as evidence accumulates.

3. `finalize` — distill

Compaction check (retrospective only): turn >30 or early context lost → warn, confirm start-of-session facts first.
Generalize: trace.jsonl + draft.yaml → strip session-specifics.
Dedup: /search-skill <intent> → report overlap verdict. Mandatory.
Split: ≥2 distinct end-goals with disjoint tools/inputs → propose split, confirm.
Preload scan: Glob $PRAXIS_DIR/reference/ for frameworks referenced → list as @include candidates.
Handoff: /edit-tool with draft.yaml + anti-patterns.md → it triages (skill/bash/agent) and writes. Never write final skill directly.
Kaizen: each retry-friction → append to $PRAXIS_DIR/thinking/kaizen/distill-skill.jsonl.

4. `status`

Read .current → print $DIR, wc -l trace.jsonl, friction count (grep -c '"friction"'), confusion count.

RISEN-lite scaffold

Structures what to gather, not final format. Full template + trace schema + annotation heuristics + split rules in reference.md.

role: {who performs — inferred from session}
intent: {generalized goal, session-specifics stripped}
steps: [{ordered actions observed}]
end_goal: {observable success criteria}
narrowing: {constraints, anti-patterns, confusion-disambiguation, resources}

Rules

Friction + anti-patterns are non-negotiable in final skill's narrowing.
Confusion flags → upfront disambiguation in final skill.
No compaction handling: warn, don't fix.

---name: distill-skilldescription: Record an interactive Claude Code session and distill it into one or more generalized skills. Captures turns, tool calls, failures, friction, and confusion signals, then hands a structured draft to edit-tool. Use when "distill skill", "record macro", "turn this session into a skill", "extract skill from session", or "/distill-skill [start|finalize]".---# Distill Skill — Session → SkillRecord a CC session, then distill it into a generalized skill via `edit-tool`. Two modes: **forward** (record as we go) and **retrospective** (parse session-so-far).## Modes| Arg | Mode | When ||---|---|---|| `start` | Forward | User invokes at/near session start. Creates trace dir, annotates turns going forward. || `finalize` | Close out | End of session. Run search-skill dedup, propose split, hand to edit-tool. || `status` | Inspect | Show current trace dir + turn count + friction/confusion tally. || *(none)* | Retrospective | Parse session-so-far. **⚠️ Warn if compaction may have occurred** (turn count high / early context lost). |## Workflow### 1. `start` — initialize trace```bash: "${PRAXIS_DIR:?PRAXIS_DIR must be set}"SID=$(date -Iseconds | tr ':+' '-')DIR="$PRAXIS_DIR/.tmp/distill-skill/$SID"mkdir -p "$DIR"echo "$DIR" > "$PRAXIS_DIR/.tmp/distill-skill/.current"```Create three files in `$DIR`:- `trace.jsonl` — append-only per-turn: `{ts, turn, user_intent, tools_used, files_touched, outcome, friction?, confusion_flag?}`- `draft.yaml` — RISEN-lite scaffold (see `reference.md`)- `anti-patterns.md` — what didn't work + whyRespond: `🎬 Recording to $DIR. Annotate turns as you go. /distill-skill finalize when done.`### 2. Annotate each turnAfter each meaningful turn, append to `trace.jsonl` — fields: `user_intent` (generalized, not verbatim) · `tools_used` · `files_touched` · `outcome` ∈ {`ok`,`retry`,`abandoned`} · `friction` (verbatim correction, if any) · `confusion_flag` (`true` if assistant asked clarifying Q → signals upfront disambiguation needed).Keep `draft.yaml` filled progressively as evidence accumulates.### 3. `finalize` — distill1. **Compaction check** (retrospective only): turn >30 or early context lost → warn, confirm start-of-session facts first.2. **Generalize**: `trace.jsonl` + `draft.yaml` → strip session-specifics.3. **Dedup**: `/search-skill <intent>` → report overlap verdict. **Mandatory.**4. **Split**: ≥2 distinct end-goals with disjoint tools/inputs → propose split, confirm.5. **Preload scan**: Glob `$PRAXIS_DIR/reference/` for frameworks referenced → list as `@include` candidates.6. **Handoff**: `/edit-tool` with `draft.yaml` + `anti-patterns.md` → it triages (skill/bash/agent) and writes. **Never write final skill directly.**7. **Kaizen**: each `retry`-friction → append to `$PRAXIS_DIR/thinking/kaizen/distill-skill.jsonl`.### 4. `status`Read `.current` → print `$DIR`, `wc -l trace.jsonl`, friction count (`grep -c '"friction"'`), confusion count.## RISEN-lite scaffoldStructures *what to gather*, not final format. Full template + trace schema + annotation heuristics + split rules in `reference.md`.```yamlrole: {who performs — inferred from session}intent: {generalized goal, session-specifics stripped}steps: [{ordered actions observed}]end_goal: {observable success criteria}narrowing: {constraints, anti-patterns, confusion-disambiguation, resources}```## Rules- **Friction + anti-patterns are non-negotiable** in final skill's `narrowing`.- **Confusion flags → upfront disambiguation** in final skill.- **No compaction handling**: warn, don't fix.

Frequently asked questions