SKILLS · SESSION-TO-SKILL DISTILLATION

skill-distill (sybil-solutions)

sybil-solutions/skill-distill (MIT license) is an operator skill for Claude Code or Codex (acting as the teacher) that distills a completed frontier-model session into a standalone produced skill for a smaller or open-weight student harness and model (such as omp running DeepSeek-V4.1-Flash). Instead of trusting a single draft, the teacher launches the student inside isolated tmux trials on a clean copy of the starting state, compares student outputs against the reference run, fixes the first divergence, and requires three trials per skill version plus your side-by-side sign-off.

1. Install skill-distill for Claude Code or Codex

Clone the repository and symlink skills/skill-distill into your agent's personal skills directory:

git clone https://github.com/sybil-solutions/skill-distill
ln -s "$PWD/skill-distill/skills/skill-distill" ~/.claude/skills/skill-distill   # Claude Code
ln -s "$PWD/skill-distill/skills/skill-distill" ~/.agents/skills/skill-distill   # Codex

# Optional: web UI verification and screenshot capture
pip install playwright pillow && playwright install chromium

At the end of a session that succeeded, prompt the teacher directly—for example:

distill this session into a skill for omp with deepseek-v4.1-flash on my local server

You can observe live student trials in another terminal with tmux attach -t distill-<task>.

2. How the 5-step teacher-student distillation loop works

The teacher reads skills/skill-distill/SKILL.md and runs an empirical refinement loop rather than one-shot summarization:

  1. Extract the reference: extract_session.py converts the Claude Code, Codex, or omp session log into a readable reference while stripping system prompts and AGENTS.md boilerplate.
  2. Draft the student skill: The teacher writes a task-specific skill starting from templates/student-skill/ covering steps, decisions, traps, and verification checks—without embedding the reference's final output or a generator script that prints it.
  3. Run clean isolated trials: Launches the student in tmux on a fresh copy of the starting state with the original prompt verbatim and global context/skills turned off where the harness allows it.
  4. Diagnose the first divergence: Compares student output (plus capture_web.py screenshots/errors for web tasks) against the reference, validates checks on the reference first, and edits the skill at the earliest failure point.
  5. Prove consistency over 3 trials: Re-runs three trials per skill version until the student matches the reference reliably, then presents reference and best student results side by side for final human approval.

3. Repository layout & student harness adapters

Included tooling (skills/skill-distill/)

PathRole
SKILL.mdCore loop instructions followed by the teacher agent
scripts/distill.pyRun bookkeeping CLI: init, trial, status, wait, evidence, verdict, ledger, report, accept
scripts/extract_session.pyConverts Claude Code, Codex, and omp logs into clean reference traces
scripts/capture_web.pyServes web apps locally, drives headless Chromium, saves screenshots and console errors
adapters/Per-harness launch wrappers for omp, pi, Codex, Claude Code, and opencode
templates/student-skill/Starter layout for each distilled student skill

Documented adapter status

Student HarnessDocumented StatusConfiguration Note
omp (oh-my-pi)TestedPrimary tested student harness in repository docs
Codex CLITested as teacherAs a student, pass the model/provider in STUDENT_ARGS
Claude CodeWrittenOpen models require ANTHROPIC_BASE_URL pointing to an Anthropic-compatible server
piWritten, untestedVerify launch flags before relying on automated runs
opencodeWritten, untestedJSON session log parser not yet implemented in extract_session.py

4. Practical boundaries & related skill guides

  • Distinct from description linters: sybil-solutions/skill-distill focuses on teacher-student session distillation for open-weight models; do not confuse it with unrelated smaller repositories that only lint YAML skill descriptions.
  • Privacy hygiene: Keep runs/ out of version control (it is git-ignored by default) because raw teacher traces contain local file paths and environment context.
  • Related Agent Skills Hub guides: Learn manual skill authoring in How to create a skill, compare local open-weight coding agents in Inkling 2 Mini local coding agent, or browse Codex CLI skills.

Frequently asked questions

What problem does sybil-solutions/skill-distill solve?

It captures a task that a frontier model completed well in Claude Code or Codex and iteratively turns it into a compact SKILL.md that a cheaper or open-weight model (running in a harness like omp) can reproduce reliably across clean trials.

Why does skill-distill require three trials per skill version?

Its rules state that a single lucky run proves nothing. Running three isolated trials from a clean starting state verifies that the distilled instructions consistently guide the student model past the task's real failure points.

Can the produced skill copy the finished code from the reference session?

No. The teacher rules explicitly forbid embedding the reference's finished output or a script that writes it; the produced skill must teach the steps, decisions, traps, and checks.

Which harnesses are tested with skill-distill?

At commit 4c3b307096, omp (oh-my-pi) is tested as a student and Codex CLI is tested as the teacher (and supports student mode via STUDENT_ARGS). Claude Code, pi, and opencode adapters are written with extra provider or testing caveats.

Primary sources