loot

Every session drops loot. Most of it dies in the chat log. Your job: find it, write it down, judge its usefulness separately from its public novelty, and ship a selected piece after the user says yes. A familiar technique can still be worth preserving or publishing; rarity is not a verdict on its usefulness.

Most of loot's value is LOOT.md: a running record of everything the user figured out. Publishing is the exception.

Loot is any valuable part of the session, not only side discoveries:

One session often holds several items. A single item often deserves several forms (repo + post + demo).

Modes

--auto always overrides shipping arguments: never ask, forge, publish, or edit any file except LOOT.md. Default capture uses steps 1 and 2a only; explicit assess also uses step 2b with searches and an outside rater. Use the project's root for LOOT.md when known, otherwise the current working directory, consistently across all modes. Append and stop. home: drafts stay inside LOOT.md; never offer or write them. If the session is already in LOOT.md and nothing new turned up, write one seen again line, not a second table.

1. Scan

Read the whole conversation and the files it touched. For a past session, or when earlier parts of this one were summarized, read the transcript instead:

node <this skill's folder>/scripts/transcript.mjs list          # recent Claude Code + Codex sessions
node <this skill's folder>/scripts/transcript.mjs read <file>   # condensed text, secrets redacted

This session's own transcript is the newest file in ~/.claude/projects/<project>/. If you couldn't read past a summary, say so in the table: early discoveries may be missing. List candidates. For each one, write down what it does and the proof that it works (test, benchmark, before/after, the user's reaction).

Keep useful local lessons even when they only apply to this user's setup or an equivalent already exists. Separate journal value from publication eligibility. Exclude private/client work and mostly third-party code from public candidates; preserve only a sanitized general lesson locally when that is appropriate. Never put secrets, credentials or personal data in the table.

2a. Rate usefulness — every capture or assessment

Usefulness means value to this user or workflow, not originality or proof of market demand. State the context and one concrete reason. Use these labels:

Use observed context, including user corrections and traceable historical checks. Do not invent hours saved, future adoption, or recurrence. You helped build this, so you lean toward High: expect most drops to be Medium or Low, and if more than two in one session are High, say why. High usefulness never raises rarity automatically, and Common never lowers usefulness automatically. Rate separately even when one axis is Unknown.

In capture mode, keep each entry short: finding, usefulness + reason, evidence source/limits, and an existing or proposed home: when helpful. For each High or Medium drop with a home:, also write the draft: described under "A better home". For historical evidence, name the inspected source and date when known; mark missing metadata unknown, state that it was not rerun, and bound the claim to what that record demonstrates. Session discovery (--list) does not rate items. Set rarity to Not assessed unless a prior assessment is available; cite its date and preserve its limits. Do not search, dispatch a rater, rerun tests, or ask what to publish merely to save a lesson. Write the journal as described below, show a concise table, then stop.

2b. Assess public rarity (only when asked)

For /loot assess, /loot 2, /loot all, assess --auto, or a review that asks for rarity, read references/assess.md and follow it: evidence, the outside rater, the rarity checklist and the full-assessment table. Capture skips this step entirely.

Show at most 7 drops, strongest first. Everything else gets one line under "noted".

Size journal entries by usefulness, not rarity. Low-value one-offs need a line; important recurring lessons may need enough detail to apply safely. Keep query/search/proof/edge detail for near misses, higher rarity claims, and publication assessment rather than burdening every captured note.

Facts in the journal come from the session. Copy numbers, names and commands exactly as they appear there; never round or reconstruct them. Anything you learned from your own web search goes only on the search: line, with its link, so a reader can tell the session's facts from the web's.

Append the findings to LOOT.md in the project root when known, otherwise the current working directory (create it if missing), dated. A drop earns a full entry only if a future session would go wrong, or redo real work, without it. Otherwise it's a one-line "noted" entry. The journal is only useful if it stays readable.

Leave out, even from "noted": one-time inventories (folder sizes, lists of what was found), standard advice the session didn't test, steps the user just asked for and got, and anything another entry already covers. A "noted" line has to name something a future session would do differently.

• Seen it before? Search LOOT.md for the same root idea first. If it's there, write seen again (first: <date> #<n>) plus only what's new, instead of a second full entry. Repeat sightings are evidence for /loot review.
• A better home. LOOT.md is the fallback, not always the best place. For each useful drop, add home: when a narrower place would do more good: a rule the agent keeps breaking → the agent's instruction file (AGENTS.md, CLAUDE.md, or whatever this agent reads); an invariant → a test; the reason behind odd code → a comment next to it; why a change was made → the commit message. Name the exact file (and section or function) when the session shows it.
• Draft it. For High and Medium drops with a home: that doesn't already hold the lesson (a user correction always gets one), put the ready-to-paste text under the entry in LOOT.md as draft: in a fenced block: the rule (a trigger plus what to do, in a few lines), the test, the comment, or a small diff. Use only facts from the session; if the home file's contents are unknown, write an append, not a diff. Capture and --auto write the draft only in LOOT.md. During an action-oriented follow-up, offer the drafts and apply each one only with the user's yes for that item. These stay local; nothing is published.

3. Forge

For each chosen item, build the finished thing in a new folder outside the current repo's history (default ../<slug>, or where the user says). Read references/forge.md for the checklist of each form. In short:

• Generalize it. Remove project names, hardcoded paths, client details and dead code. It must run from a clean clone with the README's steps. Run it.
• Name it. Short, memorable, says the job. Check that the name is free: gh search repos <name>, npm view <name> (exit 1 means free).
• Tagline. One line that tells a stranger what it does and for whom.
• Logo. Simple, one or two colors, readable at 16px, works on light and dark.
• Social preview. A 1280×640 card (logo, name, tagline) so shared links show an image instead of a blank GitHub card.
• README. Result first, then quickstart, then how it works.
• Proof. A test, a benchmark, or a before/after. Never invent numbers.
• Common, chosen anyway? The user may publish a Common item. Then it ships as a guide, not a discovery: no "new", "first" or "only" claims, and the README links the closest alternatives the search found. Say so in the manifest so the user publishes it knowingly.
• Read cold. The writer misses its own filler. Give each README and post to a fresh agent that hasn't seen the session (or, without one, reread it as a stranger) with references/forge.md → "Read cold". Fix what it flags.

Skills: if the chosen form is a skill, follow the skill-factory skill that ships next to this one (../skill-factory/SKILL.md), handing it the item's evidence (query, search results, proof, edge) as the starting spec. Skip steps 3–5 for that item: skill-factory tests, reviews and gates the release itself.

4. Check (never skip)

1. Scan every folder you will publish for secrets:

   • always: node <this skill's folder>/scripts/scan.mjs <folder>
   • also, if gitleaks is installed: gitleaks dir <folder>, and gitleaks git <folder> when the folder has git history.

   Fix every finding, or mark a false positive with loot:allow on that line and say why. Look at every warn line by hand. Never push existing git history that gitleaks hasn't scanned; without gitleaks, publish from a fresh git init instead.

2. Read every file that will be published. Look for personal data, client names, internal hostnames, private repo links and code under another license.
3. Show the user a manifest: each destination (repo name, public or private, blog draft or live), the files, the tagline. Ask for a clear yes. A yes covers exactly that manifest, nothing more.

5. Ship

Read references/ship.md for commands and fallbacks. Use your own tools first; fall back to handing the user a ready-to-run command or file.

• Repo: gh repo create, description, topics, push.
• Post: dev.to or Hashnode as a draft when a token is already configured; otherwise a Markdown file. Medium: Markdown plus import instructions.
• Launch posts (Show HN, X, Reddit): drafts in a gitignored launch/ folder, for Epic by default and for Rare when the user asks. Never post them.
• Finish with links to everything shipped and anything left for the user.

6. Review (/loot review)

Ratings from one session are a guess. Evidence builds up over time:

1. Read LOOT.md. Group entries that are the same thing seen again (same root idea, even if worded differently).
2. Refresh usefulness and evidence when something changed: it came up in 3 or more sessions, it gained proof (users, a benchmark, someone asked for it), or a new search finds nothing equivalent anymore. In ordinary review, preserve prior rarity with its date or mark it Not assessed; use no web search or outside rater. If the user requests a rarity reassessment, use step 2b and its outside rater.
3. Mark what went stale: an entry that's no longer true (the bug got fixed upstream, the tool it beat added the feature, a later entry replaced it) gets stale: <date> #<n>, <why> in the review section, so a future session doesn't act on it.
4. Show what moved on each axis and why. Write a dated "review" section to LOOT.md; never rewrite old entries. Offer publication only when the user is exploring publication; useful Common items remain eligible if selected.

Use what the agent has

Rules

• Nothing goes public without the user's yes on the exact manifest.
• Never ask for, type or store credentials. If a tool isn't signed in, fall back.
• Never publish secrets, personal data, or client or employer work.
• Respect licenses: don't relicense code you didn't write.
• No invented proof: no fake benchmarks, users, quotes or star counts.
• Write in the user's voice from the chat, not like a press release.