Toolify

Toolify

Review the current session for anything worth turning into a reusable tool, then triage each candidate one at a time and build the approved ones. This runs only when the user types /toolify.

If the /toolify invocation included a focus area (text after the command), bias the hunt toward it; otherwise review the whole session. Toolify mines the session so far: invoked mid-task, say so and suggest a re-run at session end for the full picture.

Operating rules

• HIGH BAR. Only surface candidates that would genuinely recur or be reused across future sessions. Kill tool clutter: three sharp candidates beat ten marginal ones. When unsure, lean toward DEFER, not propose.
• Do not crawl the filesystem broadly. No find /, no recursive greps over large trees. Scope every inspection to the known paths named below and the specific files this session actually touched.
• RECOMMEND first, build ON APPROVAL only. Never create a tool, or edit an existing one, without an explicit "Yes".

Step 1 - Load the deferred ledger

The ledger is TOOLIFY.md, bundled in this skill's own folder next to SKILL.md. Resolve that folder from where this SKILL.md actually lives (a standard install is ~/.claude/skills/toolify/, but plugin installs live elsewhere) and use the resolved path everywhere this skill or its references mention the skill folder. This local file is the live, authoritative ledger. Any backup or cross-device sync of it is the host's concern (never this skill's), and that mechanism must treat this file as source of truth and never overwrite it with an older copy. When running from a plugin install, a plugin update replaces this folder, ledger included: if the ledger holds any entries, remind the user of that once per session before they update.

• Read it. If it does not exist, recreate it from the bootstrap template in references/ledger-format.md, then read it.
• If the file exists but is missing any of the three sections, append the missing section(s) with the placeholder at the bottom.
• If an entry is malformed or truncated, surface it to the user rather than silently skipping it.
• Hold every entry in mind: ## Entries and ## Learnings feed the Step 3 cross-reference, ## Self-improvements feeds Step 8.
• Entry formats and bump/resurface bookkeeping for all three sections live in references/ledger-format.md; read it before any ledger write.

Step 2 - Analyze the session for tool candidates

Mine three sources:

1. The conversation itself: tasks performed, repeated manual steps, multi-step procedures executed, gotchas / roadblocks / workarounds discovered, and any "had to figure out X" moment. Recurring friction and hard-won knowledge are the richest seams.
2. Files created or changed this session: scripts, configs, and helpers written this session. A standalone script is often a tool waiting to be packaged. Read the specific files the session touched. If the session was in a git repo, git status and git diff --stat can confirm what changed. Do not scan the whole disk.
3. The tools this session USED. This is where improvements to EXISTING tools hide. Enumerate the skills, agents, hooks, and commands that fired this session, plus any that plainly should have fired but did not (no crawl needed: the session already knows what it invoked). For each, ask: did it underperform, miss a case, produce a wrong or clunky result, fail to trigger when it should have, or show stale content (moved paths, superseded facts)? Each yes is an IMPROVEMENT candidate; record the tool's absolute path and the specific gap.

Hunt ABSENCE-shaped candidates, not just friction: ask "what did this session do entirely by hand, start to finish, that no existing tool owned?" Friction points at existing tools' gaps and yields improvements; absences are where NEW tools hide, and they do not announce themselves (a smooth freehand procedure feels fine in the moment). Name at least one absence candidate per run or state explicitly that none exists.

For each NEW-tool candidate, pick the best tool TYPE using the rubric and decision heuristic in references/type-rubric-and-dedup.md; read it whenever the session yields NEW-tool candidates. It also covers flagging an existing tool for promotion to an automation.

Step 3 - Dedup and cross-reference (always on)

Before presenting anything:

• Dedup NEW-tool candidates so a duplicate is never proposed. Scope each check to the candidate's own type, plus a near-neighbor type when the call is close (for example skill vs command); never run the full inventory sweep for every candidate. The per-type lookup table (which paths to Glob / Grep, no broad crawl) lives in references/type-rubric-and-dedup.md. If any dedup Glob returns zero results, that is suspect, not proof of absence: confirm with ls <directory> before treating the category as empty. If a candidate substantially overlaps an existing tool, drop it or reframe it as an improvement to that tool, and say which. IMPROVEMENT candidates skip dedup (their target already exists) but still go through the ledger cross-reference.
• Cross-reference the TOOLIFY.md ledger from Step 1, both candidate-facing sections (## Entries for tool candidates, ## Learnings for deferred learnings). Match on what the candidate DOES, not its name (names are generated fresh each session; read each entry's What-it-does line and judge semantic overlap). If a candidate matches a previously deferred entry, mark it RESURFACED, cite the original defer date and the times-seen count, and raise its priority. A candidate that keeps coming back is a strong build signal. A resurfaced LEARNING re-enters the Step 7 lane with its ledger context cited, and repeat sightings argue for promoting it out of the ledger into its recommended home. Run this cross-reference even if the session produced no new candidates, in case it resurfaced a deferred one.

Step 4 - Present the candidate analysis

Show a concise ranked list. For each candidate:

• Name and one-line description
• NEW: recommended tool type and why. IMPROVEMENT: the target tool, the specific gap, and the proposed edit in one line.
• Reuse signal (where in the session it showed up; how often it would recur)
• Dedup result (nothing similar exists, or overlaps <tool>; improvements: n/a)
• RESURFACED note if previously deferred (date + times seen)

Keep it tight. If no NEW candidate clears the bar, say so plainly. A candidate RESURFACED from the ledger in Step 3 still goes through Steps 4-5 (resurfacing raised its priority). Only when there is nothing new AND nothing resurfaced, skip to Step 7 (the memory pass still runs).

Step 5 - Triage each candidate, one at a time

For EACH candidate, pick a recommended disposition FIRST: build, drop, or defer, judged from its reuse signal, dedup result, and resurface history (a resurfaced candidate with 2+ sightings leans build; a marginal one-off leans defer or drop). Then call AskUserQuestion (one question, header "Toolify") with these three options, the recommended one ordered first with "(Recommended)" appended to its label and the one-line why stated in the question text:

• "Yes, build it" - approve it (for improvements: approve the edit).
• "No, drop it" - discard this candidate.
• "Defer to TOOLIFY.md" - log it for later.

Do NOT add a "Chat about this" option: the harness's auto-added "Other" free-text box (or a normal typed message) already is the user's in-flow override. Treat that text as an instruction for THIS candidate (change the tool type, merge with another candidate, narrow scope, discuss, and so on), act on it, then re-present or continue.

Handle each answer:

• Yes -> add to the build queue as <candidate> | new <type> | remove-ledger-entry: yes/no or <candidate> | improve <existing tool's absolute path>. The flag records whether a TOOLIFY.md entry exists for this candidate (a resurfaced one does) so Step 6 can remove it after the build. Do not build mid-loop; build after triage in Step 6.
• No -> skip it. If it was a RESURFACED ledger entry, delete that entry from TOOLIFY.md now (an explicit drop retires the candidate; otherwise it re-presents forever). Keep it deferred only if the user says so in the Other box.
• Defer -> append it to TOOLIFY.md now per references/ledger-format.md (## Entries for tool candidates, improvements included); a RESURFACED entry is bumped in place per that file, never duplicated.
• Other (free text or a typed message) -> act on the instruction or discuss, then continue.

Naming pass (after the LAST candidate is triaged, before building): approved NEW tools need names; improvements keep their existing tool's name. For each new tool, propose a name that fits the tool type and matches its folder's conventions: kebab-case, concise and descriptive, verb- or domain-led, styled like the existing tools in that folder, no collision with an existing tool name. Ask in ONE AskUserQuestion call (header "Name", one question per tool; more than 4 approved tools = a second call), first option " (Recommended)" plus one sensible alternative; the auto-added "Other" box lets the user type their own. Record each chosen name and use it as the tool's name / slug / folder in Step 6.

Step 6 - Build the approved queue (on approval only)

After triage and naming, handle each queued item by dispatching ONE subagent per tool. Run builders serially by default; never more than 2 in flight, raised only on hardware known to handle it. Pick a capable model for each builder: authoring quality compounds across every future use of the tool, so do not cheap out here. Use a single build pass normally; when a subtle defect in a high-stakes tool would be costly, run the build through a draft, adversarial-review, and synthesize workflow.

A dispatched subagent never sees this SKILL.md, so the dispatch prompt MUST contain, explicitly:

1. NEW tool: the chosen name and tool type from triage. IMPROVEMENT: the existing tool's absolute path plus a revise-mode instruction (surgical edit closing the specific gap; do not rewrite what works).
2. A one-paragraph spec: what the tool does (or what the gap is), its reuse signal, and absolute paths to the session files/scripts it packages or the tool it edits.
3. The authoring guidance to read first: the absolute path of an installed authoring skill for the tool's type if one exists (check ~/.claude/skills/), otherwise the per-type basics in the builder contract.
4. The RESOLVED absolute paths of this skill's references/builder-contract.md and references/hardening-checklist.md (from the skill folder resolved in Step 1; never assume ~/.claude/skills/toolify/), plus this instruction: "Read and follow the builder contract at the path above in full. It carries the conventions, the hardening requirement, and the exact completion-report shape."

Reject any completion report that is missing the 6-class hardening enumeration the contract requires (hardening is the step builders most often skip). For an improvement, the enumeration covers the revised tool as a whole.

While builders are in flight and the concurrency cap leaves no build work to start, run the Step 7 learnings lane rather than idling. It touches different files, needs no build results, and its dispositions are independent of what the builders return.

After a tool is successfully built, if its build-queue line says remove-ledger-entry: yes, REMOVE that entry from TOOLIFY.md (a deferred candidate that becomes a tool leaves the ledger). Archival stays out of toolify's scope; if the host keeps a backup or archive of its tools, confirm it syncs after the session's builds.

Completion report

The completion-report template lives in references/builder-contract.md (the file every builder subagent reads). When building inline instead of via a subagent, follow the same contract.

Then summarize what was built, improved, deferred, and dropped.

Step 7 - Flag memory-worthy learnings (secondary lane, do not auto-write)

Separately from tools, list the session's gotchas, roadblocks, and learnings that are worth REMEMBERING but are not themselves tools (a platform gotcha, a workaround, a confirmed preference). For each, apply the placement ladder BEFORE offering dispositions: 0. A tool home REPLACES memory. Knowledge that lives, or could live, in a skill/agent/hook/command gets NO memory entry: duplication is bloat. This runs backwards too: when a learning's content already lives in a tool, any memory duplicating it should be retired. Only knowledge with no possible tool home reaches rung 2.

1. Skill/agent home first. Task-specific knowledge belongs inside the skill or agent that runs that task (a reference file or SKILL.md section), so it loads only when that task recurs. If a matching tool exists, the recommended disposition is "add to ", not a memory.
2. Persistent memory only for broad things. The host's persistent memory (auto memory, CLAUDE.md, or equivalent) is reserved for knowledge that cuts across many tasks and sessions (who the user is, cross-project preferences, platform facts hit constantly). It fills too fast otherwise. If the host has no persistent memory configured, defer to TOOLIFY.md or skip instead.

For each learning, say in one line what it is and why it is worth keeping, then offer the ladder-appropriate disposition first plus the alternatives: add-to-tool (when a home exists), save-to-memory (broad only), defer-to-TOOLIFY.md, or skip. Do not write anything automatically; wait for the user's go-ahead. Keep this lane clearly separate from the tool lane above.

Defer-to-TOOLIFY.md parks the learning in the ledger's ## Learnings section (format per references/ledger-format.md) with the same resurface mechanics as tool candidates; it leaves the ledger on a later save or explicit drop.

Step 8 - Toolify self-check (last, near-zero tax)

Audit this RUN of toolify itself. Surface only real friction: a candidate noticed only after presenting, a step whose instructions were ambiguous this run, a dedup path that returned confusing results, a contradiction between SKILL.md and a reference file. If nothing dragged, say "toolify ran clean" and stop.

If something did drag: cross-reference the ledger's ## Self-improvements section first (same resurface mechanics; a repeat sighting raises priority, and two or more sightings argue hard for applying the fix). Then for each issue call AskUserQuestion (one question, header "Toolify") with: "Fix toolify now" (make the surgical SKILL.md or reference-file edit), "Defer to TOOLIFY.md" (log it under Self-improvements), "Drop it". Never edit toolify's own files without the explicit yes. A fixed or dropped issue leaves the ledger.

Reference files

• references/type-rubric-and-dedup.md - the Step 2 tool-type rubric and decision heuristic plus the Step 3 per-type dedup lookup table.
• references/builder-contract.md - the complete contract every Step 6 builder subagent reads: conventions, per-type authoring basics, hardening enumeration, and completion-report shape.
• references/hardening-checklist.md - failure-mode classes every built tool must be hardened against in Step 6 (dependencies, input ambiguity, output safety, failure surfacing, environment limits, secrets).
• references/ledger-format.md - the exact ledger entry templates and bump/resurface bookkeeping for all three TOOLIFY.md sections.
• TOOLIFY.md - the bundled deferred-candidate ledger (Steps 1, 5, 7, 8). Live ledger; any copies elsewhere are snapshots.