selfskill-mine

SelfSkill Mine

Turn the user's own transcript history into personalized Claude Code skills. Read local .jsonl files from ~/.claude/projects/, find workflows they repeat, and write one SKILL.md per workflow into ~/.claude/skills/.

Runs entirely inside this session — no external service, no separate API key. Nothing leaves the machine.

When to use

• "mine my skills", "generate skills from my history", "selfskill", "run selfskill", /selfskill
• User wants Claude to look at past sessions and create reusable skills
• Bootstrapping a fresh ~/.claude/skills/ from their own work

Don't use this for installing community skills (point to a marketplace) or authoring one skill by hand.

Parameters (defaults if unspecified — state them back to the user)

• min_occurrences — min sessions a workflow must appear in (default 3)
• max_skills — max skills to generate this run (default 10)
• dry_run — preview only, write nothing (default false)
• incremental — only mine sessions newer than the last run (default true)
• transcripts_dir (default ~/.claude/projects) · output_dir (default ~/.claude/skills)

Steps

1. Confirm scope

One line back to the user, e.g.:

Mining ~/.claude/projects for workflows that repeat ≥3×, writing up to 10 skills to ~/.claude/skills/. Incremental: on. Dry run: off.

2. Read run state (incremental + dedup)

• Read ~/.claude/skills/.selfskill/state.json if it exists: { "version":1, "lastRunAt": <ms>, "generatedSkills": [slugs] }. Missing/unreadable → treat as first run (lastRunAt: 0).
• Glob ~/.claude/skills/*/SKILL.md to list slugs that already exist on disk. Union with generatedSkills → the known set. Never regenerate a skill already in the known set; never overwrite an existing skill.

3. Locate + window transcripts

• Glob **/*.jsonl under the transcripts dir. Empty → stop, tell the user there's nothing to mine.
• Sort by file mtime, newest first — skills should reflect how they work now.
• If incremental and lastRunAt > 0, keep only files modified after lastRunAt. If that leaves nothing, stop and tell them to re-run with incremental off for a full pass.

4. Sample sessions — context-safe, in batches

Reading 60 full transcripts at once will blow the context window and silently truncate. Instead, work in batches of ~10 files:

• For each file, Read only the first ~60 lines (these .jsonl files are large; the head holds the opening prompt + first tool calls, which is what identifies a workflow).
• Per file, distill a 3–5 line summary: the user's initial prompt · the first 3–6 tool calls Claude made · any commit/PR/deploy that ended it.
• Discard sessions with fewer than 3 turns.
• Keep a running list of these compact summaries; discard the raw file contents before reading the next batch so context stays bounded. Cap total at ~60 sessions; if more exist, say so.

5. Cluster repeated workflows

From the summaries, find multi-step sequences appearing at least min_occurrences times — e.g. "run migrations → restart dev server → smoke-test endpoint", "open PR → wait for CI → squash merge", "scaffold shadcn component → wire variants → hook to form".

Per cluster record: a kebab-case slug, a one-sentence when-to-use, 3–7 concrete steps (with the exact commands the user actually runs), and the count of sessions it came from. Rank by occurrences × step count; keep at most max_skills. Drop any cluster whose slug is in the known set (step 2). None left → report and suggest lowering min_occurrences.

6. Synthesize SKILL.md files

For each surviving cluster, write to the Anthropic skill spec:

---
name: <slug>
description: <one sentence, present tense, starts with a verb>
---

# <Title Case Name>

## When to use
- <trigger>
- <trigger>

## Steps
1. <concrete action / exact command>
2. ...

## Notes
- Mined from <N> of your past sessions.
- <caveat or related skill>

Rules: frontmatter name == slug · description one verb-first sentence · valid markdown, not wrapped in fences · only encode steps actually visible in the transcripts — do not invent · reference the real commands they run.

7. Write the files

With Write, create ~/.claude/skills/<slug>/SKILL.md. If dry_run, write nothing — print proposed paths + a preview of each instead. If a slug somehow collides, suffix -v2, -v3 rather than overwrite.

8. Update state

Unless dry_run, write ~/.claude/skills/.selfskill/state.json with version:1, lastRunAt = now (epoch ms), and generatedSkills = previous list ∪ newly written slugs. This is what makes the next run incremental.

9. Report

• N sessions scanned · M considered (this window) · K workflows above threshold · J written · skipped (already existed).
• Table of new skills with one-line descriptions.
• "Restart Claude Code or run /help to load the new skills."

Notes

• Never send transcripts to an external service — stay in this session.
• Generated skills must obey the Agent Skills format so Claude Code auto-discovers them.
• Incremental state + the known-set check mean repeat runs are cheap and never duplicate work — the core advantage over a one-shot dump.
• The selfskill npm CLI (npx selfskill mine) mirrors this for headless/CI use (it does use your own ANTHROPIC_API_KEY).