agentleFS
symonhesymonhe/homebrew-club/skills/zettelkasten/SKILL.md

zettelkasten

Skill1 starsChanged 3 months agoMITView on GitHub

Capture atomic notes as local markdown files with YAML frontmatter, tag them, link them, and query them back with "what have I already captured about X". Use when the user wants to take notes, capture a thought or idea, build a second brain or personal knowledge base, set up a Zettelkasten or slip box, asks "what do I already know about", "have I written about this before", "pull my notes on", or mentions atomic notes, note linking, backlinks, or tagging a note. Also use before starting a new project, to surface what the user already captured that applies to it.

5 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions5 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 5

    1. HybridAIOne/hybridclaw★ 162same name
    2. eddmann/jeeves★ 2same name
    3. brainsforai/brains-skills★ 1same name
    4. weininghui/skills★ 1same name
    5. Dmytro-Kopylov-personal/zettelkasten-skill★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Leave it empty the rest of the time and let overlap do the work.

    line 30
  2. Very specific:

    Link it, with a type and a reason: After ztk new, the script prints notes sharing tags.

    line 49
  3. Distinctive:

    If that is not comfortable, a second capture surface is genuinely easy, because capture is only ever "append one file":

    line 81
  4. Distinctive:

    Do not let the surface become the project.

    line 88

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Zettelkasten

A slip box that lives in a folder. One note, one idea, one markdown file. No database, no account, no dependencies beyond Python 3.

Quick start

export ZTK_DIR=~/notes          # wherever you want them
scripts/ztk init
scripts/ztk new "The claim you just had, in one line" --tag pricing --tag churn
scripts/ztk find --search "pricing"

The one idea that makes this work

A note is not bound to a project. Projects come and go; tags are the durable spine.

"Relevant to project X" is a derived view: a note surfaces for X when its tags overlap X's keyword lexicon in taxonomy.yaml, whether or not X existed when the note was written. So a note captured today maps itself to a project started next month, with no re-tagging.

Practically: tag projects: only when a note is clearly about that project's work. Leave it empty the rest of the time and let overlap do the work.

Capturing (this is your job as the agent)

The user drops a thought. You turn it into an atomic note.

  1. Write the body first. One idea, a few sentences, standalone so it reads without the conversation it came from. If the thought contains two ideas, make two notes.
  2. In their words, not the source's. A quote pasted from an article is not a note. Rewrite the idea; keep the source on a line underneath if it matters. Copying is the single most common way these systems die, because nothing copied ever gets recombined.
  3. Title is the claim, not the topic. "Onboarding is where activation is won", not "onboarding thoughts". A title you can agree or disagree with is a good title.
  4. Do not interpret in the body. Capture what they actually said. All the interpretation belongs in the tags and links, where it can be changed later without rewriting the thought. A note you editorialised is a note you cannot trust in a year.
  5. Tag from the existing lexicon in taxonomy.yaml where a term fits. Reaching for a term that is not there yet? Add it to candidates:, do not invent it inline. That one habit is what stops a tag list becoming 400 tags used once each.
  6. Link it, with a type and a reason. After ztk new, the script prints notes sharing tags. Add real connections with --link refines:<id>, or by writing them into the note's ## Links section:

    ## Links
    
    - refines [[20260801-first-run-matters]] because activation is downstream of it
    - contradicts [[20260715-growth-is-acquisition]]

    Types: refines, contradicts, supports, extends, is_example_of, folgezettel. The type is the reason, and the clause after it is the better reason. A bare [[id]] reads as related, which records that two notes touch without saying how, and is the weakest edge in the box.

    Links go in the body, not the frontmatter, so that Obsidian's graph can see them.

  7. Capture cheap. A seed with no links beats a perfect note you did not write. Come back with ztk review.

contradicts is the most valuable edge you can store. It is the one a tag overlap will never find for you.

Where you capture from

Thoughts do not arrive at a desk. They arrive in the car, on a walk, at 11pm.

The intended surface is a terminal session you reach from your phone, over remote control or SSH. That sounds like a compromise and is not: the terminal is already the whole app, so there is nothing to build, nothing to install on the phone, and no second copy of your notes to keep in sync. Talk to the session, it writes the file.

If that is not comfortable, a second capture surface is genuinely easy, because capture is only ever "append one file":

  • A Telegram bot is the cheapest. It gives you voice notes for free, works from a lock screen, and needs no app review. Route the message to ztk new.
  • A one-page front end, a text box and a submit button, if you would rather type.

Do not let the surface become the project. It is a text box and a shell call. The box still works on day one with nothing but the terminal.

Querying

ztk find <project>            rank notes by overlap with that project's lexicon
ztk find --search "topic"     same ranking, free text, no project needed
ztk links <id>                forward links, plus backlinks derived on read
ztk review                    what is promotable, and what is unconnected
ztk validate                  schema and vocabulary check across every note

The workflow that pays for all of it

When the user starts anything new, query the box before you ask them a single question.

Not "tell me about your idea" and then an interview from zero. Instead: run ztk find on the topic, read back what they already captured, and interview them from there. They arrive with two years of scattered thinking already on the table, including the parts they had forgotten and the times they argued with themselves.

That is a running start instead of a cold start, and it is the entire return on having captured anything. Capture is the necessary half. This is the sufficient half.

Revisiting

ztk touch <id> when a note comes up again. At 3 touches it flips to promotable, which is the signal that an idea has earned more than a note: a project, a draft, a decision.

Backing it up

Notes are plain files. git init in ZTK_DIR and commit is enough, and it gives you history. Anything that syncs a folder works. There is deliberately no built-in sync: phase one is files you own, and adding a database before you have a hundred notes is solving a problem you do not have yet.

It is already an Obsidian vault

Point Obsidian at ZTK_DIR and open it. Nothing to migrate: it was markdown the whole time. Tags, backlinks and the graph view all work, the last two specifically because links live in the body rather than the frontmatter.

Point a graph tool like graphify at the same folder when you want edges you did not write yourself. Link by hand as you capture, because that thinking is the point, then let a graph tool find what you missed.

Details

REFERENCE.md has the full schema, the scoring model behind find, the link vocabulary, the documented failure modes each design choice guards against, and how to grow the taxonomy without it sprawling.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.