| name | reshelf-catalog |
| description | Survey the user's WHOLE reshelf shelf — every project they catalogued in their reshelf macOS app, whether or not it was cloned to disk — so nothing they shelved gets forgotten. This is the companion to the `reshelf` skill: that one reads the source of repos already cloned to ~/reshelf/repos; THIS one reads the app's full catalog (live store + JSON backups) so it can also surface picks the user saved but never downloaded. Trigger it whenever the user wants the big-picture of their collection rather than code from one clone: "what's on my top shelf?", "everything I've shelved", "my whole catalog / collection", "did I miss cloning something?", "what did I save for X that I haven't downloaded yet?", "what's shelved but not cloned", "recap/overview of my shelf", "top-shelf picks I forgot", "what have I collected for <topic> overall", or comparing/choosing across saved-but-not-cloned options. It lists the catalog with clone status, highlights the not-cloned gap (especially top-shelf), recommends fits across the full shelf, and can pull a not-cloned repo's README from GitHub on demand. When the user then wants to READ or borrow actual source, hand off to the `reshelf` skill (which needs the repo cloned). Do NOT use it for: developing the reshelf app itself (its Swift/UI code), reading source of an already-cloned repo (use `reshelf`), or discovering brand-new projects on the open web. |
reshelf-catalog — your whole shelf, including what you never cloned
The user runs reshelf, a macOS app that catalogs open-source repos and clones the
keepers to disk. The sibling reshelf skill reasons over the cloned source in
~/reshelf/repos/<Category>/<repo>. But the app's catalog is bigger than what's on
disk: it tracks everything the user shelved, each tagged with a status —
topShelf (their best picks), collector (kept around), yardSale (on the way out).
This skill reads that catalog so the user never loses track of something they meant to
keep — especially top-shelf picks they forgot to clone.
Where the data lives (no app, no MCP needed)
~/reshelf/catalog.store live SwiftData store (SQLite) ← primary
~/reshelf/backups/catalog-*.json timestamped JSON exports ← fallback
~/reshelf/repos/<Category>/<repo> the actual clones (for clone-status join)
Each catalog record carries: name, category, GitHub URL, short/long description,
stars, license, tags, fit score, status, added date. That's enough to survey,
compare, and recommend without cloning or hitting the network.
How to work through a request
1. Map the whole shelf (always start here)
bash ~/.claude/skills/reshelf-catalog/scripts/catalog-map.sh
bash ~/.claude/skills/reshelf-catalog/scripts/catalog-map.sh --status topShelf
bash ~/.claude/skills/reshelf-catalog/scripts/catalog-map.sh --category "AI / Agent"
bash ~/.claude/skills/reshelf-catalog/scripts/catalog-map.sh --uncloned --status topShelf
bash ~/.claude/skills/reshelf-catalog/scripts/catalog-map.sh --search <term>
bash ~/.claude/skills/reshelf-catalog/scripts/catalog-map.sh --tsv
The summary shows totals, a cloned / total breakdown by status and by category,
and the headline list of top-shelf picks not yet cloned. Each row is flagged
[cloned] (on disk) or [ shelf] (catalogued only).
Notes that keep results correct:
- The script prefers the live store and silently falls back to the newest JSON
backup; it prints which source it used. If the app is open and you suspect very
recent edits aren't reflected, mention that the backup may lag.
- Clone status is joined on the GitHub repo slug (URL basename), because the app
clones into a folder named after the repo, not the catalog name. Catalog category
names (
AI / Agent) also differ from on-disk folder names (AI Agent) — rely on
the script's flag, don't infer clone status from folders yourself.
2. Pin down intent: survey, gap-check, or recommend
- Survey / recall ("what's on my shelf for X", "recap my collection") — list the
relevant slice with clone flags so the user sees the full picture at a glance.
- Gap-check ("did I miss something", "what should I have cloned") — lead with
--uncloned, usually scoped to --status topShelf. These are the high-intent saves
that never made it to disk.
- Recommend ("best thing I saved for Y") — reason across the whole shelf, not
just clones, using the catalog metadata (relevance, stars, license, recency-by-added,
fit score). Name a clear pick and a runner-up; say whether each is already cloned.
3. Go deeper only when asked
The catalog gives you descriptions, stars, license and tags — often enough. When the
user wants more on a not-cloned repo:
- Read its README from GitHub without cloning — fetch the repo page or raw README
(
gh repo view <owner>/<repo> if gh is available, else the raw URL). Summarize
what it is and whether it fits.
- Suggest cloning it if they want to actually study or borrow code — that's the
reshelf app's job (right-click → Clone Repository). Once cloned, switch to the
reshelf skill to read the real source.
4. Recommend, with the clone state made explicit
Best fit for <goal>: <repo> [cloned ✓ | not cloned]
Why: <relevance, stars, license, fit — from the catalog>
GitHub: <url>
Next: <if cloned → "open it with the reshelf skill"; if not → "clone it in the app, then read it">
Runner-up: <repo> — <when you'd pick it instead> [clone state]
Be honest when the shelf is thin for a topic. A weak forced pick is worse than "you
haven't shelved much here; closest is X, and Y is worth saving."
Relationship to the reshelf skill (don't overlap)
- This skill = the index: the full catalog, clone status, the not-cloned gap,
cross-shelf recommendations, README-without-cloning.
reshelf skill = the source: reading, learning from, and borrowing code from
repos already cloned to ~/reshelf/repos.
When a survey lands on a cloned repo the user wants to study, hand off to reshelf.
When reshelf finds a needed repo isn't on disk, this skill can confirm it's shelved
and where it sits.
Guardrails
- Read-only. Don't write to
catalog.store, the backups, or the clones. Surveying
and recommending only; the user manages the shelf in the app.
- Don't run or install anything from the catalog just to inspect it.
- Respect licenses before suggesting code be borrowed (the catalog shows the SPDX
field;
NOASSERTION means verify on the repo).
- Don't touch the reshelf app's own code — that's a separate development task, not
this skill.
