Denote-Org Skills

Overview

This skill enables Claude to work with Denote-based Personal Knowledge Management (PKM) systems at scale. Denote is a simple yet powerful note-taking system for Emacs that combines file naming conventions, org-mode structure, and knowledge graph links. This skill provides procedural knowledge and executable scripts for handling 3,000+ file knowledge bases efficiently.

When to Use This Skill

Claude should use this skill when:

1. Working with Denote files - Files named

   YYYYMMDDTHHMMSS--title__tag1_tag2.org

2. Large-scale PKM systems - Knowledge bases with hundreds or thousands of org files
3. Knowledge graph navigation - Following

   [[denote:TIMESTAMP]]

   links across files
4. Multi-silo management - Searching across multiple Denote directories (~/org/, ~/claude-memory/, project docs/)
5. Literate programming - Executing org-mode code blocks with

   :tangle

   and

   :results

   options
6. Denote metadata extraction - Parsing file names and org-mode frontmatter
7. Org-mode as primary collaboration format - When both

   .org

   and

   .md

   exist for the same content, treat the org file as the primary, authoritative source and use markdown only as an export/share format.

What is Denote?

Denote is a note-taking system created by Protesilaos Stavrou that uses:

• File naming:

  YYYYMMDDTHHMMSS--title__tag1_tag2.org

  • Timestamp = Unique identifier (Denote ID)
  • Title = Hyphen-separated (supports 한글/Korean)
  • Tags = Underscore-separated (English)

• Org-mode frontmatter:

  #+title:      Title
  #+date:       [2025-10-21 Tue 10:53]
  #+filetags:   :tag1:tag2:tag3:
  #+identifier: 20251021T105353
  

• Knowledge graph:

  [[denote:20251021T105353]]

  links between files

• Silo concept: Separate directories for different knowledge domains

Validated with 3,000+ org files in production PKM systems.

Knowledge Base Structure

Location:

~/org/

(symlink to

~/sync/org/

) Scale: 3,100+ org files

Main Directories

bib/

meta/

notes/

journal/

llmlog/

Content Areas

Philosophy, Science, Programming, AI, Education, Literature, Spirituality, etc.

How to Find Files

# Find by Denote ID
fd "20251217T105827" ~/org/ --type f

# Find by tag
fd "__llmlog" ~/org/ --type f

# Find by title keyword
fd "wsl2" ~/org/ --type f

# Search content
rg "검색어" ~/org/ -t org

# List recent files
ls -lt ~/org/llmlog/*.org | head -10

Reference

For detailed knowledge base configuration, see

~/org/AGENTS.md

Core Capabilities

Important: Scripts are executed via Bash, not Python import. Use the CLI commands shown below.

Behavioral rule: When reading org-mode documents, use structured approach: headings → history → focused sections. Only use grep as secondary tool.

1. Denote File Name Parsing (✅ Implemented)

CLI Usage:

# Parse a file (filename + frontmatter)
python3 ~/.claude/skills/denote-org/scripts/denote_parser.py ~/org/path/to/file.org

# Parse filename only
python3 ~/.claude/skills/denote-org/scripts/denote_parser.py --filename "20251021T105353--제목__tag.org"

# JSON output (recommended for parsing)
python3 ~/.claude/skills/denote-org/scripts/denote_parser.py --json ~/org/path/to/file.org

Example output (--json):

{
  "path": "/home/user/org/llmlog/20241127T161109--제목__tag1_tag2.org",
  "filename_meta": {
    "timestamp": "20241127T161109",
    "title": "제목",
    "tags": ["tag1", "tag2"],
    "ext": "org"
  },
  "frontmatter": {
    "title": "제목",
    "identifier": "20241127T161109",
    "filetags": ["tag1", "tag2"],
    "date": "[2024-11-27 Wed 16:11]"
  }
}

When to use:

• Extracting Denote ID from filename
• Getting title and tags without manual parsing
• Processing multiple files in batch

2. Org Headings TOC (✅ Implemented)

CLI Usage:

# Extract table of contents from org file
python3 ~/.claude/skills/denote-org/scripts/org_headings_toc.py ~/org/path/to/file.org

Example output:

1	히스토리
1	로그 :LLMLOG:
2	[2024-11-27 Wed 16:11]
3	git 리포지토리에서...

Format:

LEVEL<TAB>TITLE

When to use:

• Quick structural overview of large org files
• Decide which sections to read in detail
• Before reading entire file into context

3. Finding Denote Files (🚧 Coming Soon)

# Not yet implemented - use glob/grep for now
fd --type f "20251021T105353" ~/org/

4. Denote Link Resolution (🚧 Coming Soon)

# Not yet implemented - use grep for now
grep -r "20251021T105353" ~/org/ --include="*.org" -l

**When to use:

• File contains

  [[denote:...]]

  links
• Need to open linked files
• Validate link integrity

5. Multi-Silo Management

5.1 Preferred org-mode reading strategy

When working with org-mode files in this environment, follow this structured process instead of treating them as plain text:

1. Identify org-context and silos

   • If a file path matches any of the following, assume it is part of a Denote/org knowledge base and prefer org-mode behavior over ad-hoc grep:

     • ~/org/**

     • ~/org/meta/**

     • ~/org/bib/**

     • ~/org/notes/**

     • ~/org/llmlog/**

     • ~/claude-memory/**

     • ~/repos/gh/*/docs/**

     • ~/repos/work/*/docs/**

   • Treat these as silos with different roles:

     • ~/org/meta

       : meta-level models, config, and system design

     • ~/org/bib

       : bibliography and reference material

     • ~/org/notes

       : long-form notes and thinking

     • ~/org/llmlog

       : LLM conversation logs and experiments
     • project

       docs/

       : per-repo documentation tied to code

2. Parse headings before content

   • For large org files, do not read the entire file into context at once.
   • Instead, first extract only:
     • The top-level headings (

       *

       ,

       **

       ,

       ***

       )
     • Their titles and hierarchy
   • Build a lightweight table of contents (TOC) and use that to decide which sections to inspect in detail.

3. Locate and summarize history sections early

   • If any heading matches common history patterns, treat it as a version/change log and inspect it early:

     • * 히스토리

       ,

       * HISTORY

       ,

       * History

       ,

       * 작업 로그

       ,

       * Changelog

       , or similar
   • Summarize:
     • How the document has evolved over time
     • Recent significant changes
     • Any explicit version markers or dates

4. Drill down into relevant sections only

   • After building the TOC and understanding history, only expand the specific headings that are relevant to the current task or user question.
   • Use grep/rg as a secondary tool to locate candidate sections, then return to structured org parsing for interpretation.

5. Prefer org over markdown when both exist

   • If both

     X.org

     and

     X.md

     exist for the same conceptual document:
     • Treat

       X.org

       as canonical for structure, metadata, and detailed reasoning.
     • Use

       X.md

       only as an export/share artifact or when the user explicitly prefers markdown.

This strategy exists to maximize collaboration on org documents as first-class knowledge artifacts, not just as flat text blobs.

Common silos:

• ~/org/

  - Main knowledge base (3,000+ files)

• ~/claude-memory/

  - AI memory system

• ~/repos/*/docs/

  - Project-specific docs

Quick Start Examples

Example 1: Parse Denote File

# Get metadata from a Denote file
python3 ~/.claude/skills/denote-org/scripts/denote_parser.py --json ~/org/llmlog/20241127T161109--제목__tag.org

Example 2: Get TOC Before Reading Large File

# First, get structure overview
python3 ~/.claude/skills/denote-org/scripts/org_headings_toc.py ~/org/notes/large-file.org

# Output: 
# 1	섹션1
# 2	하위섹션
# Then read only relevant sections

Example 3: Find Denote File by ID (using standard tools)

# Until denote_finder.py is implemented
fd "20251021T105353" ~/org/ --type f
# or
find ~/org -name "*20251021T105353*"

Common Pitfalls

Korean Encoding

Problem: 한글 filenames may cause encoding issues Solution: All scripts use UTF-8

Large Files

Problem: Reading entire large org file exceeds context Solution: Use

org_headings_toc.py

Available Scripts

scripts/
├── denote_parser.py       ✅ Parse filenames and frontmatter (--json)
├── org_headings_toc.py    ✅ Extract TOC from org file
├── denote_finder.py       🚧 Coming soon
├── denote_linker.py       🚧 Coming soon
└── denote_rename.py       🚧 Coming soon

See Also

• Denote Package by Protesilaos Stavrou
• Org-mode documentation