Zettelkasten note tool

Create, manage, and operate a Zettelkasten slip-box note system using the zk.py CLI script. Use this skill whenever a user wants to build or use a Zettelkast...

Security Scan

The skill is internally consistent with a local Zettelkasten CLI: it only manages markdown files in a user-specified vault and does not request external credentials or unusual system access, but there are minor implementation details (shell invocation, file I/O) you should be aware of before running.

Purpose & Capability

Name/description match the provided code and instructions: a single-file Python CLI to create and manage a local Zettelkasten vault. No unrelated binaries, env vars, or network endpoints are requested.

Instruction Scope

SKILL.md and the CLI operate locally on a vault (default ~/Zettelkasten) and instruct the agent to deliver the script to the user. The runtime instructions do not direct data to external endpoints or request unrelated files. Note: the script reads all .md files under the vault and opens an editor via os.system, which executes a shell command — see user guidance.

Install Mechanism

No install spec; this is instruction-only with a bundled script file. No downloads or third-party package installs are performed by the skill itself.

Credentials

Only optional environment variables are used (ZK_VAULT to set vault location and EDITOR to open files). These are appropriate and proportional to a local note-management tool; no credentials or unrelated secrets are requested.

Persistence & Privilege

always:false and user-invocable:true. The skill writes files to the user-specified vault (normal for this purpose). It does not modify other skills or global agent configuration.

Assessment

This skill appears to do what it says: manage a local Zettelkasten vault and needs only optional ZK_VAULT and EDITOR environment variables. Before installing or running it: - Review the script yourself (it is provided) and run it from a user account you control. The code is local-file oriented and does not phone home. - Be cautious with the EDITOR environment variable: the script uses os.system(f'{editor} "{path}"'). If EDITOR is set to a malicious string (or contains shell metacharacters), that could execute undesired shell commands. Prefer setting EDITOR to a trusted program (e.g., vim, nano) or modify the script to use subprocess.run([...], shell=False). - Be mindful of ZK_VAULT: if you override the vault path, the tool will scan and read all .md files under that path. Don’t point it at directories containing sensitive files. - If you plan to allow autonomous invocation by an agent, consider whether automatic file creation/editing is acceptable; you can require explicit user invocation instead. - If you want extra safety, run the script in a confined environment (different user account, container, or VM) until you’re comfortable with behavior.

znote: Zettelkasten CLI Note Manager

A single-file Python CLI tool (zk.py) implementing the full Zettelkasten method as described in the Desktop Commander / Obsidian Practical Setup Guide. No dependencies beyond Python 3.8+ stdlib. Creates and manages a local markdown vault compatible with Obsidian.

Inputs

• Python 3.8+ (no pip installs needed)
• Optional: ZK_VAULT environment variable to set vault location (default: ~/Zettelkasten)
• Optional: EDITOR environment variable for note editing (default: nano)

Vault Structure

~/Zettelkasten/
  00-Inbox/        ← fleeting notes (quick captures)
  10-Literature/   ← one note per source, in your own words
  20-Permanent/    ← atomic notes, one idea, fully linked
  30-MOC/          ← Maps of Content (navigation layers)
  40-Templates/    ← markdown templates for each type

Workflow

Step 1: Deliver the script

Copy zk.py to /mnt/user-data/outputs/zk.py and present it to the user via present_files. Also deliver README.md.

Step 2: User installs

chmod +x zk.py
cp zk.py ~/.local/bin/zk        # optional: make globally available
export ZK_VAULT=~/Zettelkasten  # add to ~/.bashrc or ~/.zshrc

Step 3: Initialise vault

python3 zk.py init
# Creates all 5 folders + 4 markdown templates

Step 4: Daily workflow

Capture (fleeting note, no friction):

zk new fleeting

Process inbox weekly (flags notes older than 7 days):

zk inbox

Write permanent notes (one atomic idea per note):

zk new permanent "Claim written as a full sentence"

Link notes — edit the ## Connections section and add [[note-stem]] links.

Promote fleeting → permanent:

zk promote "fragment of title"

Generate Map of Content when a topic has 8+ notes:

zk moc "Topic Name"

Step 5: Maintenance commands

zk links                    # find orphaned notes (no links in/out)
zk links "note title"       # show forward + backlinks for one note
zk graph                    # ASCII link graph of entire vault
zk stats                    # counts, top tags, orphan count
zk search "query"           # full-text search with highlights
zk list --folder permanent  # list notes in a specific folder
zk list --tag psychology    # filter by tag

Output

• zk.py — single-file Python CLI, ~400 lines, no dependencies
• README.md — full usage guide with workflow and tips
• A local markdown vault fully compatible with Obsidian

Note Types & Templates

Type	Folder	Filename pattern	Template fields
Fleeting	00-Inbox/	{timestamp}.md	created, status
Literature	10-Literature/	{date}-{slug}.md	created, status, source, author, tags
Permanent	20-Permanent/	{date}-{slug}.md	created, status, tags, source, Connections, Source
MOC	30-MOC/	MOC-{slug}.md	created, status, tags, linked notes

Key Method Rules (from the guide)

• One idea per permanent note — if a second idea appears, create a new note and link
• Titles are claims, not topics: "Attention is a finite resource" not "Attention"
• Link from day one — every permanent note needs at least one [[link]]
• Tags supplement links — use broad tags (#psychology), not fine-grained ones
• MOCs emerge late — only create when navigation actually becomes difficult
• Inbox rule — fleeting notes must be processed within 7 days

Notes / Edge Cases

• The script uses [[double-bracket]] wiki-link syntax identical to Obsidian — vaults are fully interoperable
• Link targets are matched by filename stem (case-insensitive)
• zk graph marks missing link targets with ⇢? in red
• --no-edit flag on new, promote, moc skips opening the editor (useful for scripting)
• ZK_VAULT env var overrides --vault flag and default path
• The zk promote command fuzzy-matches on filename and note body content
• Templates folder is excluded from stats/orphan counts automatically