From org-roam-toolkit
Org-mode formatting and org-roam note management via emacsclient. Never use Read/Write/Edit on roam notes directly. Triggers: roam note, org-roam, org-mode, .org files, Zettelkasten, backlinks
How this skill is triggered — by the user, by Claude, or both
Slash command
/org-roam-toolkit:org-roamThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides comprehensive org-mode knowledge and org-roam note management via emacsclient.
This skill provides comprehensive org-mode knowledge and org-roam note management via emacsclient.
Two modes of operation:
NEVER use Read/Write/Edit tools on roam notes. Always use MCP tools or skill commands instead.
Why:
Trigger patterns:
/roam/ or /org-roam/Use these MCP tools directly for all org-roam operations. No Bash permissions needed.
Available tools:
| Tool | Description |
|---|---|
roam_create_note | Create org-roam note |
roam_search_title | Search by title |
roam_search_tag | Search by tag |
roam_search_content | Full-text search |
roam_get_backlinks | Get backlinks for a note |
roam_create_link | Create links between notes |
roam_add_reading_history | Add to quarterly reading log |
roam_add_toolkit | Add to quarterly toolkit |
roam_add_to_read | Add TODO to read later |
roam_list_tags | List all tags |
roam_doctor | Run diagnostics |
Quick examples:
# Create note
roam_create_note(title="My Note", tags=["topic"], content="content here")
# Create reference note with source URL
roam_create_note(title="Article", subdirectory="reference", sourceUrl="https://...")
# Search
roam_search_title(query="react")
roam_search_tag(tag="javascript")
# Links
roam_get_backlinks(title="React")
roam_create_link(source="React Hooks", target="React", bidirectional=true)
# Reading history (NOT org-roam node)
roam_add_reading_history(title="Article", url="https://...", tags=["topic"], summary="...")
# Toolkit (NOT org-roam node)
roam_add_toolkit(title="SnapKit", url="https://...", category="library")
If MCP tools are unavailable, fall back to ortk-emacs-eval --pkg=org-roam-skill (installed by Homebrew on PATH):
# Create note (tags MUST be a list, not string)
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"Title\" :tags '(\"tag\") :content \"text\")"
# Create with large content (recommended for >1KB content)
TEMP=$(mktemp -t org-roam-content.XXXXXX)
echo "Large content..." > "$TEMP"
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"Title\" :content-file \"$TEMP\")"
# Temp file auto-deleted!
# Search
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-search-by-title \"search-term\")"
# Backlinks
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-get-backlinks-by-title \"Note Title\")"
# Link notes
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-bidirectional-link \"Note A\" \"Note B\")"
# Attach file
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-attach-file \"Note Title\" \"/path/to/file\")"
# Diagnostics
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-doctor)"
Key principle: Package auto-loads on first call, then stays in memory - no repeated loading overhead.
Notes are organized into subdirectories within org-roam-directory:
| Directory | Use Case | Examples |
|---|---|---|
daily | Daily logs, journals, fleeting thoughts | 今日计划、随想、会议记录 |
reference | External sources, articles, docs | Wikipedia 摘要、新闻、API 文档、教程 |
projects | Project-specific notes | 项目名相关、任务跟踪、进度记录 |
main | Conceptual knowledge (default) | 技术原理、概念笔记、学习总结 |
read_history | Reading log (NOT org-roam nodes) | 文章阅读记录,按季度文件组织 |
toolkit | Tool/resource collection (NOT org-roam nodes) | 库、工具、服务、API 收藏 |
Classification rules (Claude auto-selects):
org-roam-skill-add-reading-history (NOT create-note)org-roam-skill-add-toolkit-resource (NOT create-note)referencedailyprojectsmainUsage with :subdirectory parameter:
# Default (main directory)
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"DNS 记录类型\")"
# Explicit subdirectory
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"项目A进度\" :subdirectory \"projects\")"
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"Wikipedia: Linux\" :subdirectory \"reference\")"
Reading history is a consumption log organized by quarterly files (e.g., 2026-Q1.org). Each article is a level-1 heading with properties. This is NOT the same as creating org-roam notes.
Add reading history entry:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-add-reading-history \"Article Title\" \"https://example.com/article\" :tags '(\"topic\") :source \"website\" :summary \"One line summary\" :points '(\"Key point 1\" \"Key point 2\") :rating 4)"
Parameters:
title (required): Article titleurl (required): Source URL:tags: List of classification tags:source: Website name (e.g., "cnblogs", "github", "weixin"):summary: One-line summary:points: List of key points:rating: 1-5 rating (optional)Result format in quarterly file:
* Article Title :topic:
:PROPERTIES:
:URL: https://example.com/article
:READ_AT: [2026-01-22 Wed 15:40]
:SOURCE: website
:RATING: 4
:END:
One line summary
- Key point 1
- Key point 2
[[https://example.com/article][原文]] | [[https://archive.today/submit/?url=...][存档]]
Toolkit is a resource collection organized by quarterly files (e.g., 2026-Q1.org). Each resource is a level-1 heading with properties. This is NOT the same as creating org-roam notes.
Add toolkit resource:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-add-toolkit-resource \"SnapKit\" \"https://github.com/SnapKit/SnapKit\" :tags '(\"library\" \"ios\" \"ui\") :category \"library\" :description \"iOS Auto Layout DSL\")"
Parameters:
title (required): Resource nameurl (required): Resource URL:tags: List of classification tags:category: Resource type (library / tool / service / api):description: One-line descriptionResult format in quarterly file:
* SnapKit :library:ios:ui:
:PROPERTIES:
:URL: https://github.com/SnapKit/SnapKit
:CATEGORY: library
:FOUND_AT: 20260122
:END:
iOS Auto Layout DSL
When creating reference notes from external URLs, use :source-url:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"Article Title\" :subdirectory \"reference\" :source-url \"https://example.com/article\" :content \"...\")"
This:
* References
- Article Title: [[https://example.com/article][original]] | [[https://archive.today/submit/?url=...][submit archive]]
Workflow:
:source-url in reference subdirectory → browser auto-opens archive.today:open-archive behavior:
:default (omitted): Auto-opens browser for reference subdirectory onlyt: Always open browsernil: Never open browserAll AI-generated notes MUST be clearly marked to identify potential hallucinations:
ai_generated tag for quick filteringGENERATOR: The AI system (e.g., claude)MODEL: The model used (e.g., opus-4.5)GENERATED_AT: Timestamp of generationRequired format:
#+filetags: :ai_generated:
:PROPERTIES:
:ID: xxx
:GENERATOR: claude
:MODEL: opus-4.5
:GENERATED_AT: [2026-01-13 Mon]
:END:
#+title: Note Title
Example with full marking:
TEMP=$(mktemp -t org-roam-content.XXXXXX)
cat > "$TEMP" << 'EOF'
* Summary
AI-generated content here...
* References
- Source: [[https://example.com][original]] | [[https://archive.today/xxx][archive]]
EOF
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"Note Title\" :tags '(\"ai_generated\" \"topic\") :properties '((\"GENERATOR\" . \"claude\") (\"MODEL\" . \"opus-4.5\") (\"GENERATED_AT\" . \"[2026-01-13 Mon]\")) :content-file \"$TEMP\")"
Important: Never omit AI marking. Users must be able to distinguish AI-generated content from human-written notes.
Simple note:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"Note Title\")"
With tags and content:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"React Hooks\" :tags '(\"javascript\" \"react\") :content \"Brief notes here\")"
With large content (recommended for complex/large content):
# Create temp file
TEMP=$(mktemp -t org-roam-content.XXXXXX)
# Write content
cat > "$TEMP" << 'EOF'
* Introduction
Content here with proper org-mode formatting.
* Details
More content.
EOF
# Create note (temp file is automatically deleted)
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"My Note\" :tags '(\"project\") :content-file \"$TEMP\")"
Critical: Tags must be a list:
:tags "tag" (string):tags '("tag") (list):tags '("tag1" "tag2") (multiple tags)Content format:
Content should be in org-mode format. For markdown conversion or general org-mode formatting, use the orgmode skill:
# Example workflow:
# 1. Convert markdown to org (orgmode skill)
# 2. Create roam note with org content (this skill)
ortk-emacs-eval --pkg=org-roam-skill \
"(org-roam-skill-create-note \"Title\" :content \"* Org content\")"
For general org-mode operations (formatting, conversion, validation), see the orgmode skill. This skill focuses on org-roam-specific operations: note creation, database sync, node linking, and graph management.
See references/functions.md for detailed parameter documentation.
By title:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-search-by-title \"react\")"
By tag:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-search-by-tag \"javascript\")"
By content:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-search-by-content \"functional programming\")"
List all tags:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-list-all-tags)"
Find backlinks (notes linking TO this note):
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-get-backlinks-by-title \"React\")"
Create bidirectional links:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-bidirectional-link \"React Hooks\" \"React\")"
This creates:
Insert one-way link:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-insert-link-in-note \"Source Note\" \"Target Note\")"
Attach file:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-attach-file \"My Note\" \"/path/to/document.pdf\")"
List attachments:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-list-attachments \"My Note\")"
Attachments use org-mode's standard org-attach system.
User says: "Create a note about React Hooks and link it to my React note"
Step 1: Search for existing note
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-node-from-title-or-alias \"React\")"
Step 2: Create new note
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-note \"React Hooks\" :tags '(\"javascript\" \"react\") :content \"Notes about React Hooks\")"
Step 3: Create bidirectional links
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-skill-create-bidirectional-link \"React Hooks\" \"React\")"
Step 4: Show user the result Present the created note path and confirm links were established.
All operations use ortk-emacs-eval --pkg=org-roam-skill which:
org-roam-skill package on first callAfter first call, functions stay in memory - no loading overhead.
Find org-roam directory:
ortk-emacs-eval --pkg=org-roam-skill "org-roam-directory"
Sync database (if needed):
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-db-sync)"
All functions use org-roam-skill- prefix:
Note Management:
org-roam-skill-create-note - Create new org-roam notesorg-roam-skill-add-reading-history - Add entry to quarterly reading log (NOT org-roam node)org-roam-skill-add-toolkit-resource - Add resource to quarterly toolkit (NOT org-roam node)org-roam-skill-search-by-title/tag/content - Search notesorg-roam-skill-get-backlinks-by-title/id - Find backlinksorg-roam-skill-insert-link-in-note - Insert linksorg-roam-skill-create-bidirectional-link - Create two-way linksTag Management:
org-roam-skill-list-all-tags - List all tagsorg-roam-skill-add-tag - Add tag to noteorg-roam-skill-remove-tag - Remove tag from noteAttachments:
org-roam-skill-attach-file - Attach file to noteorg-roam-skill-list-attachments - List attachmentsUtilities:
org-roam-skill-check-setup - Verify configurationorg-roam-skill-get-graph-stats - Graph statisticsorg-roam-skill-find-orphan-notes - Find isolated notesorg-roam-doctor - Comprehensive diagnosticsSee references/functions.md for complete function documentation with all parameters and examples.
Installation: See references/installation.md for:
Troubleshooting: See references/troubleshooting.md for:
Quick diagnostic:
ortk-emacs-eval --pkg=org-roam-skill "(org-roam-doctor)"
emacsclient returns Elisp-formatted data:
"result" (with quotes)("item1" "item2")nil or no output42Strip quotes from strings and parse structures as needed.
'("tag") not "tag"Org-mode Formatting (no emacsclient needed):
Org-roam Operations (via emacsclient):
Quick access patterns:
references/org-syntax.mdreferences/timestamps.mdreferences/links.mdreferences/installation.mdreferences/functions.mdreferences/troubleshooting.mdnpx claudepluginhub ibenjamin/org-roam-toolkit --plugin org-roam-toolkitGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.