Distill Skill

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

1. 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 → 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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: digital-stoic-org
• Source: digital-stoic-org/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.