denote-org

name	denote-org
description	Use this skill when working with ~/org/ directory, Denote files (YYYYMMDDTHHMMSS--title__tags.org), or org-mode knowledge bases. Provides scripts for: parsing Denote filenames/metadata, extracting org file TOC, and navigating 3,000+ file PKM systems. Trigger on: ~/org/, ~/org/llmlog/, ~/org/bib/, Denote ID parsing, org heading extraction.

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

Directory	Purpose	Scale
bib/	Bibliography notes (books, people, concepts)	800+ files
meta/	Meta topics (programming, tools, workflows)	-
notes/	Personal notes and collections	-
journal/	Daily/weekly journals	-
llmlog/	AI/LLM conversation logs	-

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 - easy to parse.

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.

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 first, then read specific sections

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