Extract Skill Candidates

Extract Skill Candidates

Find the workflows someone runs again and again with their AI tools but never encoded as reusable skills. The evidence already exists: every request they typed into Claude Code, Claude Cowork, Codex, or Cursor is still on their machine. This skill distills that history, talks with the user about what they actually do, and answers in the chat with the patterns their own requests show — the ask that keeps coming back, the block they keep pasting, the chain they run by hand, the calendar rhythm they never noticed.

The output is that answer. Building the skills on it is a separate piece of work, deliberately out of scope here.

What this reads and writes

Everything happens on the user's machine. The skill reads the conversation files the four tools keep locally and writes exactly two small text files to ~/.skill-candidates/ — one holding the user's own requests, one holding counts computed from them. A few MB, created in seconds. Nothing installs, no accounts, no API keys, nothing is sent anywhere. Deleting ~/.skill-candidates removes everything.

Intent

• Know-how firewall > output richness. Every file of this skill and every answer it produces may reveal WHAT the flow does (gather → filter → group → spot patterns) but never HOW its stages decide: no candidate-qualification heuristics, grouping taxonomy, pattern-spotting criteria, or chaining strategy at reconstruction fidelity (the plumbing inside the scripts is mechanism, not methodology). When unsure whether an explanation teaches the engine, cut the explanation and keep the result. The same firewall covers identifying detail in the skill's own files: no client names, internal IDs, or pointers to unpublished skills. In answers, names from the user's own history are their data on their machine: quotes keep the user's words; finding titles stay name-free unless the user asks otherwise.
• Surprise > confirmation, and both ride on the user's data — never on methodology exposition. Lead with what memory cannot hold: the word-for-word block re-pasted for months, the follow-up chain run by hand, the calendar rhythm, the user's own "again" wording aggregated. A finding the user already knows ("you ask about invoices monthly") supports; it never leads. Generic findings any listicle could contain = failure, regardless of polish.
• Counted by tools, interpreted by judgment. Every number in an answer comes from the computed counts or a reproducible search — never from eyeballing the text. If a count cannot be reproduced, the finding drops.
• The user's voice is part of the method, not decoration: ask what they do before concluding anything, present the evidence-based picture as a hypothesis, and let their corrections replace it. Never proceed on an unconfirmed guess about someone's own work.
• Privacy posture > capability and polish. Nothing installs, nothing leaves the machine, and the one-sentence disclosure before writing the two local files is never smoothed away. No cloud calls, no API keys, no telemetry.
• The chat is the deliverable. No report files, no links to documents the user must open, no process narration — never mention steps, reviews, scripts, digests, or internal checks. The user sees a couple of plain progress lines, real questions, and the findings — all in the user's own language, and all passing the one-read test for a non-engineer.
• "Good" = 3–5 findings specific to this user's history — each named in plain words, carrying one verified number, quoting the user's own words, and ending in a proposed skill name with its takes/produces/fires sketch — at least one finding the user likely did not consciously know, and at most one about how they talk to their tools rather than the work itself. "Good enough" = fewer or thinner findings with honest confidence markers, conversation-derived items labeled as such; the firewall holds unconditionally.
• An empty-but-honest answer beats a padded one: if the evidence cannot ground even one specific finding, say so plainly and find candidates by conversation instead. If the user pushes past the findings — asks for the skills to be built or for the encoding how-to — state plainly where this skill's job ends.

Workflow

The flow, in order: look → ask → distill → confirm → dig → answer. The verification pass before answering is silent — the user never hears about it.

1. Look for history — read-only

Check what exists using file listing only (no message text, no scripts):

• Claude Code: ~/.claude/projects/*/*.jsonl
• Claude Cowork: ~/Library/Application Support/Claude/local-agent-mode-sessions/
• Codex CLI: ~/.codex/sessions/ and ~/.codex/archived_sessions/
• Cursor: ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb (Windows: under %APPDATA%; Linux: under ~/.config/Cursor/)

If nothing exists or only a handful of files: skip straight to the conversation path (references/conversation-guide.md), and say why in one plain sentence.

2. Ask, disclose, and distill — one turn

In a single message: tell the user in one plain sentence what was found and ask the 2–3 genuine questions from references/conversation-guide.md — what they do, what a normal week looks like, anything to leave out. Include the one-sentence disclosure: reading those conversations and writing two small text files to ~/.skill-candidates/, nothing installs, nothing leaves the machine, delete the folder anytime — and wait for their explicit go-ahead in the same reply as their answers.

Once they reply, run the extractor that fits the machine:

• macOS with developer tools present (xcode-select -p succeeds): python3 <skill_dir>/scripts/extract_digest.py
• macOS without developer tools — never invoke python3, it would trigger an install dialog: osascript -l JavaScript <skill_dir>/scripts/extract_digest.js
• Windows: powershell -NoProfile -ExecutionPolicy Bypass -File <skill_dir>/scripts/extract_digest.ps1 — this variant cannot read Cursor's storage; if the look found Cursor history, say so in one plain sentence and cover that ground with the conversation questions instead
• Linux: python3 <skill_dir>/scripts/extract_digest.py — and if python3 is missing or older than 3.9, say so in one plain sentence and use the conversation path instead

If the extractor fails for any other reason, say so in one plain sentence and use the conversation path — never leave the user with a raw error as the last word.

All variants accept --since YYYY-MM-DD (PowerShell: -Since). If signals.txt reports SCALE=LARGE in its totals, re-run bounded to roughly the last six months and tell the user in one plain line that the look is focused on recent months because the history is unusually big.

3. Form and confirm the picture

Read ~/.skill-candidates/signals.txt. Combine what it shows (where the activity is, what repeats, when) with what the user answered, and reflect a short picture back: their main work areas, each tied to something concrete ("most of your activity is around X — roughly N requests since March"). Present it as a hypothesis and ask what's wrong or missing. Their corrections replace the picture — do not argue with someone about their own work. Exclusions they name are honored everywhere downstream.

4. Dig where the signals point — area by area

Work through the confirmed areas one by one, not just where literal repetition is loudest. For each area:

• Search ~/.skill-candidates/digest.tsv with several wordings per candidate, not just one — people phrase the same ask differently across months, and the routines that matter most rarely repeat word-for-word.
• Read the matching sections of signals.txt (repeated requests, repeated blocks, "again"-wording, rhythms, chains) as leads to chase, not as the candidate list. Work routines from the confirmed areas outrank patterns in how the user talks to their tools — at most one such interaction habit makes the answer, and only when its cost is genuinely large.
• Watch the date spans: dozens of repeats inside a day or two is a batch job or an existing automation, not a human routine — treat it accordingly.
• Every count that will appear in the answer must come from signals.txt or a reproducible search over the digest — never from impression.

Apply the candidate lens and the finding shapes in references/findings-format.md, and name each proposed skill per references/naming-guide.md.

5. Verify silently, then answer in the chat

Before answering, run the check in references/review-gate-prompt.md — a separate agent re-verifies every number and quote against the two local files (give it the drafted findings, the two file paths when they exist, and the user's statements for conversation-derived items). This check runs on conversation-only answers too — there the file checks simply don't apply. Fix what it rejects; drop what cannot be verified. None of this is mentioned to the user.

Then deliver the findings directly in the chat, shaped per references/findings-format.md: 3–5 findings, each with a plain-words name, one number, the user's own words quoted, and a proposed skill name with its takes/produces/fires sketch — then one sentence naming which candidate to encode first, then one closing line on where this skill's job ends. The answer's first line is the "Looked at N requests..." opener — nothing before it: no lead-in, no note about checks or fixes, no "here's what I found". No file is written unless the user explicitly asks to save the answer somewhere.

When the history was unusually big even after bounding, add the plain closing line from references/conversation-guide.md — at that volume, a proper deep pass is its own piece of work.

Additional Resources

Reference Files

• references/findings-format.md — the candidate lens, the finding shapes with their wow templates, and the chat-answer contract
• references/conversation-guide.md — the opening questions, the conversation-only path, and the closing lines (boundary, large-history)
• references/naming-guide.md — how to name proposed skills: kebab-case rules, reserved words, prefix families
• references/review-gate-prompt.md — the silent verification pass run before answering

Example Files

• examples/sample-findings.md — a complete fictional example of the chat answer this skill produces