Mine reusable skills from your coding agents' transcripts. Works with Claude Code, OpenAI Codex CLI, and any other agent via a small exporter. Every candidate is scored by confidence and utility, weighted by how the trace it came from actually turned out (successful / meh / failed), and only the strong, novel ones are surfaced for your review. You approve, edit, or reject each one from a VS Code panel or the ** /review-skills** command. Approved skills are written as real
SKILL.md
files; every candidate, approved or not, is kept so mining keeps improving.I kept telling my coding agent the same things: run the tests before saying it's done, stop hardcoding ports in parallel test suites, reuse fixes we had already worked out. By the next session, those patterns were gone. Skills solve this, but writing one by hand after finishing a task is extra work most people skip.
Agent platforms usually answer with built-in memory: the agent learns from your sessions, its behavior changes, and you don't see exactly what it learned. I didn't want that running over transcripts with my code, infrastructure details, and occasional pasted secrets.
skill-extractor makes that process visible. It runs on your machine, keeps state as plain JSONL, pattern-redacts secrets before anything reaches a model, and only installs a persistent instruction after risk lint and your approval. The result is a markdown skill you can open, edit, or delete.
For one developer, it turns repeated fixes into reusable skills. For a team, it produces reviewable material for a shared skill catalog.
./install.sh # macOS: launchd timer + VS Code panel + /review-skills
Not on macOS? The engine is portable; run it under any supervisor:
python3 engine/extractor.py --loop 1800 # mine every 30 min, forever
Review from wherever you work: the VS Code panel pops up when skills are
discovered, /review-skills
runs the same flow in Claude Code, and
python3 engine/review.py list
is the raw CLI. Interval, model, scope, and
sources live in config.json
(SKILL_EXTRACTOR_INTERVAL=900 ./install.sh
changes the timer).
Be clear-eyed about what this tool is. It is a loop with three powerful parts:
It mines your private agent traces. Your transcripts contain your code, your infrastructure names, your mistakes, and sometimes pasted secrets. Reading and segmentation happen entirely on your machine; state files are created0600
in0700
directories. Keep projects you cannot afford to leak out of mining altogether withscope
/exclude_projects
. -
It may send excerpts to a remote LLM. The mining prompt (transcript excerpts: user messages, tool inputs and outputs) goes to the backend you configure. Secret redaction is on by default: private keys, JWTs, AWS/API keys, bearer tokens,SECRET=
/TOKEN=
env lines, and URL-embedded passwords become[redacted:...]
before any prompt leaves the process. Redaction is pattern-based and best-effort, not a guarantee. The default backend is your localclaude
CLI, which means Anthropic's API; any other backend requires an explicitack_command_backend: true
. Forzero egress, point the command backend at a local model:
"mining_backend": "command",
"mining_command": ["ollama", "run", "llama3"],
"ack_command_backend": true
Installed skills change your agent's future behavior. A mined skill is model output; once installed it is a persistent instruction your agent will follow in later sessions. Every install therefore runs a risk lint (pipe-to-shell bootstraps, credential-file access, disabled safety flags, exfiltration shapes, hidden persistence, prompt-injection phrasing, broad destructive commands). Flagged skills refuse to install until you explicitly acknowledge the findings (--acknowledge-risk
on the CLI, a modal confirmation in VS Code), and the acknowledgement is recorded indecisions.jsonl
. The lint surfaces risk; it does not certify safety. Installing a skill is closer to merging code than dismissing a notification. Treat it that way.
Private traces in, model in the middle, agent instructions out. The defaults are privacy-first, but the loop is only as safe as your review of what you install and your choice of what to mine. Details: SECURITY.md.
Multiple agents, one queue. Pluggable trace sources share one cursor, one budget, and one review queue:claude_code
,codex
(project identity from the sessioncwd
, imported sessions skipped to avoid double-mining, exec exit codes feed outcome scoring), andjsonl_dir
for any other agent via a ~30-line exporter to the canonical record shape.Six skill categories, not just technical procedures: techniques, workflows, standing preferences, guardrails learned from failures, automations, domain knowledge.Outcome-weighted scoring. Candidates from traces that demonstrably worked score higher; failures still teach guardrails.A learning loop. Your install/reject decisions (with comments) calibrate future mining prompts and score priors toward your taste.Incremental and cheap. Byte cursors and segment fingerprints mean idle runs make zero LLM calls;max_segments_per_run
caps spend.Any scheduler, any mining LLM. launchd installer on macOS;--loop
anywhere; systemd/cron/Task Scheduler recipes and non-Claude mining backends indocs/PORTABILITY.md.
python3 engine/extractor.py # run a mining pass now
python3 engine/extractor.py --status # counts: scratch / pending / installed / decided
python3 engine/extractor.py --full # ignore cursor, re-scan all history
python3 engine/extractor.py --self-test # sanity-check the pipeline, no traces needed
python3 engine/review.py list # pending candidates (JSON, with risk labels)
python3 engine/review.py show <id> # full candidate
python3 engine/review.py install <id> [--edits edits.json] [--acknowledge-risk]
python3 engine/review.py reject <id> --comment "why"
Enable more sources in config.json
:
"sources": ["claude_code", "codex"], // default: claude_code only
"jsonl_dirs": ["~/my-agent-traces"] // any agent, via canonical JSONL
| Category | What it captures | Outcome weight* |
|---|---|---|
technique |
||
| concrete technical procedures (commands, debugging recipes) | 0.45 | |
workflow |
||
| multi-step ways of organizing work | 0.40 | |
preference |
||
| standing instructions and repeated corrections you keep expressing | 0.15 | |
guardrail |
||
| what-to-avoid learned from failures | 0.10 | |
automation |
||
| repeated manual sequences that could be one skill | 0.35 | |
domain |
||
| reusable domain knowledge / heuristics | 0.30 |
*How much the source trace's outcome scales utility. A technique
from a
failed trace is suspect; a preference
or guardrail
expressed in a failed trace is just as valid. Conversation-heavy segments are mined too; that is where preferences hide.
Scoring: confidence
(is this real and generalizable?) and utility
(how valuable if reused?), blended with measured outcome quality: tool error
rate, user sentiment, and the next task's opening message as trailing
feedback. Only candidates clearing the thresholds in config.json
surface for review; everything else stays in scratch, never deleted.
Learning: every decision feeds back twice. The miner sees your recent installs and rejections with your stated reasons (propose more like these, none like those), and per-category approval rates nudge scores toward your demonstrated taste, capped so a few decisions cannot swing everything. This is why rejections ask for a comment: "too project-specific" teaches the miner more than a silent dismissal.
trace sources (adapters) claude_code | codex | jsonl_dir
│
▼
extractor.py: incremental read -> segment by task -> heuristic outcome
-> redact -> mine (your LLM backend) -> score -> dedupe
-> candidates.jsonl (scratch) -> pending.json (surfaced)
│
├─ VS Code panel / /review-skills / review.py
├─ install -> ~/.claude/skills/<name>/SKILL.md + decisions.jsonl
└─ reject -> decisions.jsonl (comment kept for learning)
| Piece | Path |
|---|---|
| Miner | engine/extractor.py |
| Core lib (parsing, scoring, state) | engine/lib.py |
| Trace-source adapters | engine/adapters.py |
| Review CLI | engine/review.py |
| VS Code panel | vscode-extension/ |
/review-skills flow |
|
skills/review-skills/ |
State lives in ~/.claude/skill-extractor/state/
: candidates.jsonl
(every
mined candidate, never deleted), pending.json
(awaiting review),
decisions.jsonl
(your calls + comments), cursor.json
(incremental reads).
Embedding this in your own application? docs/INTEGRATION.md has the Python API, CLI/JSON contracts, and data schemas, with a runnable examples/embed_minimal.py.
skill-extractor installs approved skills locally, for you. If your team needs mined skills to flow through shared review, risk scanning, policy checks, and an audit trail before anyone's agent uses them, that governance layer is what Surenode builds on top of this engine: same mining, with a governed catalog instead of a local folder.
Python 3.9+(the engine is stdlib only, no pip installs)- A mining LLM: the
Claude Code CLI by default (no API key needed), or any command backend, including fully local models - macOS for the bundled installer; any OS for the engine itself
VS Code optional (/review-skills
and the CLI work without it)
python3 -m pytest tests/
See CONTRIBUTING.md: the engine stays stdlib-only, new agents arrive as adapters, and commits are signed off (DCO).
./uninstall.sh # removes timer/hook/extension/skill, keeps mined state
./uninstall.sh --purge # also deletes the state store