shelf-skills

📚 shelf

Capture & recall skills for AI coding agents.

Save the links you'll forget. Get the right one back at the moment you need it.

---

The problem

You find a genuinely useful tool in a newsletter. You save it. It joins a pile.

Four months later you're mid-project and need exactly that thing — and you have no idea it's already sitting in your notes. So you search the web from scratch, and the pile grows by one.

The gap isn't storage. It's recall at the moment of need.

A tidy pile is still a pile.

What this is

Two Agent Skills that turn a raw dump of links into a library that surfaces itself when it's relevant.

Skill	What it does
🗃️ shelf-save	Dump links, articles, or documents. Run it once. Get one clean note per thing — fetched, structured, deduped, indexed.
🔎 shelf-find	Searches those notes automatically whenever you're choosing a tool mid-work. You never have to remember it exists.

Your library, after a week of newsletters

Notes cross-reference each other because each one is read in full when it's written — something a bookmark folder structurally cannot do.

The index, generated for you

Every entry is filed by the problem it solves, not what the product calls itself.

---

A link is only the common case

Plenty of things worth saving can't be fetched — newsletter tracking redirects, paywalls, login walls, JS-only pages, PDFs behind a CDN. So shelf-save takes whatever carries the content:

You give it	How	It does
🔗 a URL	one per line in inbox.md	fetches the page
📄 pasted text	paste into inbox.md, as messy as you like	reads it as given, no fetch
📎 a document — PDF, docx, txt	drop it in upload_documents/	reads the file
🖼️ a screenshot	drop it in upload_documents/	reads the image

Or hand any of them over in chat — "save this: …" — if you'd rather not open the folder.

[!TIP] Pasting isn't a fallback. You saw the real content, so the note is better than a fetched one — and it's marked confidence: high accordingly.

No syntax to learn. Paste an article straight in, blank lines and all. The skill works out where one item ends and the next begins, then tells you what it found before writing anything, so a stray note-to-self is easy to catch.

One document can become several notes — a conference PDF covering five tools gets five notes. A paper or spec stays one note with a longer body. Files you drop are never moved or deleted.

---

Install

Core spec only, no agent-specific frontmatter — so these run unmodified on any of the 40+ skills-compatible agents. Only the install location differs.

Unzip dist/shelf-save.zip and dist/shelf-find.zip into your agent's skills directory:

Agent	Directory
Claude Code	~/.claude/skills/
Codex	$HOME/.agents/skills/ (user) · .agents/skills/ (repo)
Cursor · Gemini CLI · Copilot · Goose · Kiro · OpenCode · Amp	see your agent's skills docs
claude.ai	upload the two zips as Skills, one at a time

You should end up with <skills-dir>/shelf-save/SKILL.md and <skills-dir>/shelf-find/SKILL.md. Some agents need one restart if the skills directory didn't exist before.

Committing to .agents/skills/ in a repo gives your whole team the skills regardless of which agent each person uses.

Requirements: your agent needs to read/write files, fetch a URL, and search text across files. Nearly all can.

---

First run

Say "process my inbox". It asks where the library should live — an Obsidian vault subfolder, or any plain folder — creates the structure, and remembers the path in ~/.tool-library-path.

You're asked once, ever. Updating the skills won't ask again, because that file lives outside any agent's config directory. Two different agents can even share one library.

your-library/
├── inbox.md            # dump URLs and pasted text here
├── upload_documents/   # drop PDFs, docs, screenshots here
├── notes/              # one note per thing you saved
├── _index.md           # auto-generated, grouped by category
└── _processed.md       # append-only archive, so nothing saves twice

Only inbox.md and upload_documents/ are yours to touch. Edit any note freely — the two underscore files are regenerated.

---

Daily use

1.  Paste links into inbox.md as you find them.     ← no tagging, no thinking
2.  Whenever you feel like it: "process my inbox."  ← it empties itself
3.  While working: "what should I use for X?"       ← recall fires on its own

That's the whole thing. Step 3 needs no command — shelf-find triggers on the shape of the question.

Anything that fails to fetch stays in inbox.md under a Failed heading with a note on how to rescue it. Nothing is ever silently dropped.

---

What a note looks like

---
title: Resend
url: https://resend.com
category: dev-tool
problem_solved: Sending transactional email without fighting deliverability
pricing: Free tier 3k emails/mo; paid from $20/mo
maturity: stable
confidence: high
tags: [email, api, backend, saas]
---
## What it is
## Use this when
## Don't use this when
## Notes

problem_solved is the entire design.

It's written as your problem, never the product's pitch — because that's the shape of the question you'll ask four months from now.

✅ "Sending transactional email without fighting deliverability" — gets found ❌ "A modern email API for developers" — invisible forever

---

Design decisions

🗂️ Plain files, no plugin

No Obsidian plugin, no REST API, no MCP server, no database, no account. Saving happens whenever your agent is open — rarely the same moment your notes app is. Nothing may require a second program to be running. Stop using these tomorrow and the library is still just files.

🤐 It admits when it has nothing

If no saved note genuinely fits, shelf-find says "Nothing in your library covers this" and offers a clearly-separated web search. It does not pad the list. One bad recommendation costs more than ten honest misses — because after the bad one, you stop asking.

🚫 Never invents facts

Any field it can't determine is written unknown. Pages behind paywalls fall back to a web search, get flagged confidence: low, and carry a visible warning in the note body.

🔒 Nothing is silently destroyed

Notes are never deleted. The processed archive is append-only. inbox.md is re-read immediately before it's cleared, so links you paste during a run survive it.

---

Customising

Categories are a starting set, not a fixed taxonomy:

dev-tool · ai-agent · marketing · design · data · fundraising · ops · research · reading

They lean toward someone building software — swap in whatever fits your work.

[!IMPORTANT] The list lives in both SKILL.md files. Edit both, or notes get filed under a category recall never searches. Existing notes keep their old category until you change them.

Moving your library: edit the one line in ~/.tool-library-path.

---

MIT · built because a pile of saved links is not a library