# 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]".

- **Type:** Skill
- **Install:** `agentstack add skill-digital-stoic-org-agent-skills-distill-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [digital-stoic-org](https://agentstack.voostack.com/s/digital-stoic-org)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [digital-stoic-org](https://github.com/digital-stoic-org)
- **Source:** https://github.com/digital-stoic-org/agent-skills/tree/main/experimental/skills/distill-skill

## Install

```sh
agentstack add skill-digital-stoic-org-agent-skills-distill-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```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 + 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`.

```yaml
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](https://github.com/digital-stoic-org)
- **Source:** [digital-stoic-org/agent-skills](https://github.com/digital-stoic-org/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-digital-stoic-org-agent-skills-distill-skill
- Seller: https://agentstack.voostack.com/s/digital-stoic-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.