Claude Code Skill

[nextlevelshit]

Might be useful, in case you want to utilize notesium API (which is super nice) with an agent like Claude Code.

Download SKILL.md

---

name: notesium
description: Interact with Notesium, a Zettelkasten-style markdown notes system. Use for creating, reading, updating, deleting notes, searching, managing links, and working with the knowledge graph.
allowed-tools: Bash, Read, Write, Grep, Glob
argument-hint: [action] [args...]

Notesium Zettelkasten Skill

Notesium is a markdown notes system with bi-directional links for building a Zettelkasten knowledge base.

Environment

• Notes directory: Set via NOTESIUM_DIR environment variable (default: $HOME/notes)
• Note format: Markdown files with .md extension
• Naming: Files use timestamp-based names (e.g., 20240115103045.md)
• Titles: First line must be H1 format (# Title)
• Labels: Single-word titles are treated as labels (like tags)

CLI Commands

List Notes

notesium list [options]

Options:

• --sort=ctime|mtime|alpha - Sort by creation time, modification time, or alphabetically
• --prefix=ctime|mtime|label - Add prefix to output
• --labels - Show only label notes (single-word titles)
• --orphans - Show notes without any links
• --color - Enable ANSI colors
• --date=FORMAT - Date format (default: 2006-01-02)

Create New Note

# Get path for new note
notesium new [--verbose] [--ctime=DATETIME]

# Create note with content
path=$(notesium new)
echo "# Note Title

Content here..." > "$path"

View Links

notesium links [filename] [options]

Options:

• --outgoing - Links from this note to others
• --incoming - Links from other notes to this note (backlinks)
• --dangling - Broken links only
• --color - Enable ANSI colors

Full-Text Search

notesium lines [options]

Options:

• --filter=QUERY - Search query with operators:
  • Space = AND (all terms must match)
  • | = OR (any term matches)
  • ! = NOT (exclude term)
  • Quoted terms for exact phrases
• --prefix=title - Show note title with each line
• --color - Enable ANSI colors

Statistics

notesium stats [--table] [--color]

Get Notes Directory

notesium home

Web API (when server is running)

Start server: notesium web --writable --port=PORT

Base URL: http://localhost:PORT/api

Endpoints

Method	Endpoint	Description
GET	/api/notes	List all notes (metadata only)
GET	/api/notes/:filename	Get single note with content
POST	/api/notes/	Create new note (requires --writable)
PATCH	/api/notes/:filename	Update note (requires --writable)
DELETE	/api/notes/:filename	Delete note (requires --writable)
GET	/api/raw/lines?filter=QUERY	Full-text search
GET	/api/raw/list	List notes with options
GET	/api/raw/links?filename=X	Get links for note
GET	/api/raw/stats	Get statistics
GET	/api/runtime	Server info
GET	/api/heartbeat	Keep server alive

API Examples

# List all notes
curl http://localhost:PORT/api/notes

# Get specific note
curl http://localhost:PORT/api/notes/20240115103045.md

# Search notes
curl "http://localhost:PORT/api/raw/lines?filter=search+term"

# Create note (POST)
curl -X POST http://localhost:PORT/api/notes/ \
  -H "Content-Type: application/json" \
  -d '{"Content": "# New Note\n\nContent here"}'

# Update note (PATCH)
curl -X PATCH http://localhost:PORT/api/notes/20240115103045.md \
  -H "Content-Type: application/json" \
  -d '{"Content": "# Updated Title\n\nNew content", "LastMtime": "2024-01-15T10:30:45Z"}'

# Delete note
curl -X DELETE http://localhost:PORT/api/notes/20240115103045.md \
  -H "Content-Type: application/json" \
  -d '{"LastMtime": "2024-01-15T10:30:45Z"}'

Note Object Structure

{
  "Filename": "20240115103045.md",
  "Title": "Note Title",
  "IsLabel": false,
  "OutgoingLinks": ["20240114092030.md"],
  "IncomingLinks": ["20240116141500.md"],
  "Ctime": "2024-01-15T10:30:45Z",
  "Mtime": "2024-01-15T10:30:45Z",
  "Lines": 10,
  "Words": 150,
  "Chars": 850,
  "Path": "/home/user/notes/20240115103045.md",
  "Content": "# Note Title\n\nContent..."
}

Zettelkasten Best Practices

1. Atomic notes: One idea per note
2. Unique titles: Titles are like APIs - make them clear and specific
3. Link generously: Connect related ideas with [[filename]] syntax
4. Use labels: Create single-word titled notes as categories/tags
5. Let structure emerge: Don't over-organize upfront

Linking Syntax

Create links between notes using wiki-style syntax:

See also [[20240115103045]] for related concepts.

Common Workflows

Find orphan notes (unlinked)

notesium list --orphans

Find all backlinks to a note

notesium links 20240115103045.md --incoming

Search for term across all notes

notesium lines --filter="search term" --prefix=title

List all labels/tags

notesium list --labels --sort=alpha

[alonswartz]

This is really cool, thanks for sharing.

A few small but important corrections:

1. Filename format

The filename examples aren't quite correct. Notesium filenames are 8-character hex values (derived from epoch time), not human-readable timestamps like 20240115103045.md.

https://www.notesium.com/docs/concepts/#note-filenames

2. Link syntax

Notesium does not use wiki-style links, but rather standard Markdown inline links, for example: [Quantum mechanics](64214930.md)

https://www.notesium.com/docs/concepts/#inline-link-format

3. CLI vs API focus (suggestion)

It might be worth focusing on the CLI or the API, rather than both at once. Each is a perfectly valid entry point, but mixing them can make the skill harder to reason about and harder to use consistently.

BTW, a while back I built an experimental addon which integrates with the Notesium API, and uses tool calls. Might be useful as a reference.

• https://github.com/alonswartz/notesium-gpt
• https://github.com/alonswartz/notesium-gpt/blob/master/gpt-tools.js

That said, for a SKILL.md, I'd probably focus on CLI integration.

Overall, great direction. It's really nice seeing Notesium be leveraged in higher-level tooling. Happy to help iterate further.