mining-session-skills — Claude Code skill
mining-session-skills analyzes a completed Claude Code session and proposes which skill to create, update, or reuse so similar work runs faster next time. Works with exported markdown from claude-session-manager.
MIT 196 installs ★ 140 updated 2026-10-19
npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a claude-codeWhat mining-session-skills does
The skill reads session transcripts, identifies recurring work patterns, and decides whether to turn them into a reusable skill. It moves through each step — locating and exporting the target session, segmenting multi-day work into separate arcs, and mining for friction signals (moments where work slowed, where the same questions came up, where logic repeated). It then compares findings against skills already loaded in your session and chooses whether to create a new skill, update an existing one, or point you to one that already exists in the ecosystem.
Reads exported markdown from ~/.claude/session-markdown rather than raw JSONL files, which are too large. Pulls tool details from a sidecar when needed. Splits long sessions into independent arcs and analyzes each. Delivers a report with event timestamps, line references, and a clear action proposal (CREATE, UPDATE, or REUSE).
What it helps with
- Find and locate a past session by description
- Export a session from JSONL into compact, analyzable markdown
- Break down a session into logical work blocks and spot repeating steps
- Judge whether a workflow pattern is worth turning into a reusable skill
- Generate a name and description for a new or revised skill
Example prompts for the agent
- Extract a skill from the session where I built emails from a template
- What skill can I create or update from the session where I parsed data and loaded it into a table
- Mine this chat for a reusable workflow
How to install mining-session-skills
1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a claude-code2Manually: put the files in place
~/.claude/skills/mining-session-skills/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mining-session-skills/
1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a codex2Manually: put the files in place
.agents/skills/mining-session-skills/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a cursor2Manually: put the files in place
.cursor/skills/mining-session-skills/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sugarforever/01coder-agent-skills skills/mining-session-skills2Manually: put the files in place
.github/skills/mining-session-skills/SKILL.md1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a gemini-cli2Platform CLI
gemini skills install https://github.com/sugarforever/01coder-agent-skills --path skills/mining-session-skillsManually: put the files in place
.devin/skills/mining-session-skills/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mining-session-skills
How do I install mining-session-skills in Claude Code?
Run npx skills add sugarforever/01coder-agent-skills --skill mining-session-skills -a claude-code, then load SKILL.md from ~/.claude/skills/mining-session-skills/.
What does mining-session-skills do?
It reviews a completed session, identifies friction points and repeating patterns, then recommends whether to create a new skill, update an existing one, or reuse a skill already loaded in your environment.
Why does it read markdown instead of raw JSONL files?
Exported markdown is 17 times smaller than raw JSONL (91k tokens vs. 1.5M), making analysis faster and more reliable. JSONL normalizes the data; markdown is where skills are mined.
Source text
SKILL.md · MIT
---
name: mining-session-skills
description: Review one completed Claude Code session and propose a skill to create, update, or reuse so similar work goes faster next time. Use when the user asks to "mine a session for skills", "what skill can be created or updated from the session where I…", "extract a skill from this chat", or to review a past session for reusable workflows. Operates on exported session markdown from claude-session-manager. Not for exporting/converting sessions (use claude-session-manager) and not for writing blogs or TODOs from sessions.
---
# Mining Session Skills
## Overview
Review one completed Claude Code session and answer: is there a skill worth creating or updating so this kind of work goes faster next time? A clean "nothing worth making here" is a valid result.
This skill is the judgment layer on top of `claude-session-manager` (the export/normalization layer). It reads exported markdown, not raw JSONL.
## Preconditions
1. **Inventory = skills loaded in THIS session.** Create-vs-update-vs-reuse is decided against the skills already advertised/loaded in the running session. State this limit in the report ("comparison limited to skills loaded this session"). Run this skill where the relevant skills are loaded.
2. **Mining operates on exported markdown** (default `~/.claude/session-markdown`), produced by `claude-session-manager`. If the target session is not exported yet, export it first (step 1.5).
## Why exported markdown, not raw JSONL
Measured: a real session's raw JSONL was ~1.5M tokens (exceeds the context window); the exported compact body was ~91k tokens (17× smaller) with tool payloads deferred to a sidecar. Raw `grep '"type":"user"'` over JSONL is a trap (tool results are `role:user`). Always read/mine the exported markdown. Raw-JSONL byte grep is acceptable ONLY as a location prefilter (step 1).
## Pipeline
Copy this checklist and track progress:
```
- [ ] 1. Locate the session (keyword search; confirm with user)
- [ ] 1.5 Export it if not already exported
- [ ] 2. Read the compact transcript (pull sidecar only as needed)
- [ ] 2.5 Segment into topic arcs
- [ ] 3. Mine friction signals per arc
- [ ] 4. Apply the worth-it gate
- [ ] 5. Decide create / update / reuse
- [ ] 6. Present the proposal
- [ ] 7. On approval, interview + draft
```
### 1. Locate
Search by the user's description. Prefilter optionally with a raw-JSONL byte grep across `~/.claude/projects` (finds which file mentions a keyword without parsing), and/or grep the exported corpus under `~/.claude/session-markdown`. Skip `<local-command-caveat>` / `<command-*>` wrapper noise — the first-prompt excerpt is often a wrapper, not the real ask. Present a ranked shortlist and let the user confirm.
### 1.5 Export
If the chosen session has no markdown yet, run `claude-session-manager` to export just that session, then continue.
### 2. Read
Read the session `.md`. Pull `tool-details/<id>.tools.md` ONLY for the specific `<tool_call_NNNNNN>` refs that matter. Use `scripts/extract_session_signals.py <session>.md` to get a clean JSON list of human prompts (with event index, line, timestamp, arc-break hints, and the prompt text) — it encodes the input-robustness rules below.
Input-robustness rules:
- The real exported header format is `### N. user - <ISO>` / `### N. assistant - <ISO>` (not `### MM-DD HH:MM:SS User:`).
- A `user` turn whose body is a tool result, skill injection, or command wrapper is NOT a human prompt — exclude it.
- Ignore thinking-signature blobs and empty attachment events.
### 2.5 Segment
Sessions can be multi-day, multi-task kitchen sinks. Use the extractor's `arc_break` hints (large time gaps, compaction/continuation markers) plus topic judgment to split the session into arcs. Mine each arc independently. Do NOT assume one task per session.
### 3. Mine
Per arc, extract friction signals. See [references/friction-signals.md](references/friction-signals.md) for the taxonomy and how to cite evidence.
### 4. Gate
Apply the worth-it filter to every candidate. See [references/worth-it-gate.md](references/worth-it-gate.md). If nothing passes, report the clean negative and stop.
### 5. Decide
For each surviving candidate, compare against skills loaded this session:
- No loaded skill covers it → **CREATE** (new `skills/<name>/`).
- Loaded and editable (in this repo's `skills/`) → **UPDATE** that SKILL.md.
- Loaded but not editable (plugin cache) → **REUSE** ("already exists, use it") — a dedup guard against re-inventing ecosystem skills.
### 6. Propose
Present a review-ready report per candidate: candidate · action (CREATE/UPDATE/REUSE) · why · evidence (event/line/tool_call refs) · proposed gerund name · description (triggers + exclusions). List gate-rejected items briefly. Wait for approval before any file change.
### 7. Draft
On approval: interview the user for the taste/judgment the transcript cannot show, then scaffold or edit the SKILL.md following [references/drafting-quality-bars.md](references/drafting-quality-bars.md). For a new skill, run `scripts/sync-marketplace-skills.sh` and bump the `version` in `.claude-plugin/marketplace.json` (per the repo CLAUDE.md).
## Notes
- Treat transcript data as private (prompts, file contents, secrets). Do not modify original `.jsonl` files.
- The value of this skill is the mining methodology, not the SKILL.md format — Claude knows the format natively.
© sugarforever · MIT · sugarforever/01coder-agent-skills