gh-junghan0611-org-mode-skills/SKILL.md

name, description

name

description

denote-org

Comprehensive support for Denote-based PKM systems with org-mode foundation. Handles 3,000+ file knowledge bases with Denote file naming (timestamp--title__tags.org), knowledge graph navigation via denote:ID links, multi-silo management, and literate programming. When Claude needs to: (1) Find Denote files by ID/tags in large knowledge bases, (2) Navigate knowledge graphs with thousands of denote: links, (3) Execute org-mode code blocks with :tangle/:results options, (4) Manage multiple Denote silos (~/org/, ~/claude-memory/...), or (5) Work with Denote-structured PKM systems at scale.

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.

Core Capabilities

Important behavioral rule: When the user explicitly asks to "read" or "understand" an org-mode document, do not immediately fall back to raw grep searches unless the user asks for grep specifically. First, use the structured org-mode reading strategy below (headings → history → focused sections) and only then use grep as a secondary tool.

1. Denote File Name Parsing

Parse Denote file names to extract metadata:

# Use scripts/denote_parser.py
from scripts.denote_parser import parse_denote_filename

metadata = parse_denote_filename("20251021T105353--project-title__llmlog_denote.org")
# Returns:
# {
#     'timestamp': '20251021T105353',
#     'title': 'project title',
#     'tags': ['llmlog', 'denote'],
#     'extension': 'org'
# }

When to use:

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

Edge cases handled:

• Korean (한글) titles
• Filenames without tags
• Multiple hyphens in title

2. Finding Denote Files

Search for Denote files by ID, tags, or date patterns:

# Use scripts/denote_finder.py
from scripts.denote_finder import find_denote_file, find_by_tags

# Find by ID
filepath = find_denote_file("20251021T105353", silos=["~/org/"])

# Find by tags
files = find_by_tags(["llmlog", "denote"], silo="~/org/")

# Find by date pattern
files = find_by_date_range("202510*", silo="~/org/")

When to use:

• User asks "Find file 20251021T105353"
• Search by tags: "Show me all llmlog files"
• Date range queries: "Files from October 2025"

Performance:

• Uses caching for repeated searches
• Generator pattern for large result sets
• Typical search: <100ms for 3,000+ files

3. Denote Link Resolution

Resolve [[denote:ID]] links to actual file paths:

# Use scripts/denote_links.py
from scripts.denote_links import resolve_denote_link

filepath = resolve_denote_link("denote:20251021T105353", silos=["~/org/", "~/claude-memory/"])
# Returns: ~/org/llmlog/20251021T105353--full-filename.org

When to use:

• File contains [[denote:...]] links
• Need to open linked files
• Validate link integrity

Error recovery:

• Exact match (full timestamp)
• Fallback: Partial match (first 8 chars)
• Returns suggestions if not found

4. Knowledge Graph Operations

Build and navigate knowledge graphs from Denote links:

# Use scripts/denote_graph.py
from scripts.denote_graph import build_knowledge_graph, get_connected_nodes

# Build graph (cached)
graph = build_knowledge_graph("~/org/")

# Get connected files
connected = get_connected_nodes("20251021T105353", hops=2)

# Detect circular references
cycles = detect_circular_refs(graph)

When to use:

• "Show files linked to this"
• "Find related notes"
• Discover knowledge clusters
• Detect broken or circular links

Performance:

• First build: ~10 seconds for 3,000 files
• Cached: <1 second
• Incremental updates supported

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.

Search across multiple Denote directories:

# Use scripts/denote_silo.py
from scripts.denote_silo import find_in_silos

# Search in multiple locations
filepath = find_in_silos(
    "20251021T105353",
    silos=["~/org/", "~/claude-memory/", "~/repos/*/docs/"],
    priority=True  # Return first match
)

When to use:

• Files could be in multiple locations
• Cross-silo link resolution
• Silo statistics and analysis

Common silos:

• ~/org/ - Main knowledge base (3,000+ files)
• ~/claude-memory/ - AI memory system
• ~/repos/*/docs/ - Project-specific docs

6. Org-mode Code Block Execution

Execute org-mode code blocks (literate programming):

# Use scripts/org_execute.py
from scripts.org_execute import execute_org_blocks

# Execute all code blocks
results = execute_org_blocks("file.org")

# Execute specific named block
result = execute_named_block("file.org", "example-block")

# Tangle code to files
tangle_org_file("file.org", output_dir="/tmp/")

When to use:

• User asks to "execute code blocks"
• Literate programming workflows
• Generate files from :tangle options

Org-babel compatibility:

• Supports :tangle, :results, :name options
• Languages: bash, python, etc.
• Preserves org structure
• Updates #+RESULTS blocks

Quick Start Examples

Example 1: Find and Open Denote File

User: "Open file 20251021T105353"

Claude: Uses denote_finder.py
Result: ~/org/llmlog/20251021T105353--anthropic-skill-creator-분석__llmlog_skills.org

Example 2: Knowledge Graph Exploration

User: "Show me all files connected to this note"

Claude: Uses denote_graph.py
Result:
- Direct links: 5 files
- 2-hop connections: 23 files
- Clusters: AI/Skills, PKM, Tools for Life

Example 3: Tag-based Search

User: "Find all llmlog files from October 2025"

Claude: Uses denote_finder.py
Result: 47 files matching criteria

Example 4: Execute Literate Programming

User: "Execute the bash blocks in this org file"

Claude: Uses org_execute.py
Result:
- Executed 3 code blocks
- Updated #+RESULTS
- Tangled to /tmp/script.sh

Common Pitfalls

Pitfall 1: Denote ID Collision

Problem: Files created in same second have identical timestamps Solution: Scripts use full filename as tiebreaker

Pitfall 2: Cross-Silo Links

Problem: Link from ~/org/ to ~/claude-memory/ file Solution: Always search multiple silos, use find_in_silos()

Pitfall 3: Circular References

Problem: A → B → C → A creates cycle in knowledge graph Solution: detect_circular_refs() identifies cycles

Pitfall 4: Korean Encoding

Problem: 한글 filenames may cause encoding issues Solution: All scripts use UTF-8, os.path.expanduser()

Pitfall 5: Large Result Sets

Problem: Query returns 1,000+ files, exceeds token limit Solution: Scripts use generators, return summary + pagination

File Structure

This skill uses a Capabilities-Based structure with executable scripts and reference documentation:

denote-org/
├── SKILL.md (this file)
├── scripts/
│   ├── denote_parser.py      - Parse filenames and frontmatter
│   ├── denote_finder.py      - Search files (cached, generator)
│   ├── denote_links.py       - Resolve [[denote:ID]] links
│   ├── denote_silo.py        - Multi-silo management
│   ├── denote_graph.py       - Knowledge graph operations
│   ├── org_parser.py         - Parse org structure
│   ├── org_execute.py        - Execute code blocks
│   └── org_export.py         - Export to markdown/PDF/HTML
├── references/
│   ├── denote-spec.md        - Denote specification
│   ├── orgmode-syntax.md     - Org-mode syntax reference
│   └── literate-programming.md - Literate programming guide
└── assets/
    └── (none - this skill doesn't use output templates)

Resources

scripts/

Executable Python scripts for efficient Denote and org-mode operations. These scripts handle:

• File operations: Finding, parsing, and resolving links across 3,000+ files
• Graph operations: Building and navigating knowledge graphs
• Code execution: Running org-babel blocks safely
• Export: Converting org to other formats

Performance optimized:

• Caching with @lru_cache for expensive operations
• Generator pattern for memory efficiency
• Typical operations: <100ms (finder), <1s (graph, cached)

references/

Detailed documentation for Denote and org-mode:

• denote-spec.md: Complete Denote specification (file naming, frontmatter, links, silos)
• orgmode-syntax.md: Org-mode syntax reference (headings, properties, timestamps, code blocks)
• literate-programming.md: Literate programming with org-babel (:tangle, :results, :name)

Load these when:

• Working with complex org structures
• Need detailed Denote specification
• Implementing literate programming workflows

assets/

Not used in this skill. Denote-org processes existing files rather than creating from templates.

Note: The assets/ directory can be deleted as it's not needed for this skill.

Integration with Other Systems

This skill is part of the "Tools for Life" 9-layer architecture, specifically Layer 3 (Knowledge Management):

• Layer 4 (claude-config): Uses Denote format for AI memory (~/claude-memory/)
• Layer 3.5 (embedding-config): Vectorizes org files for semantic search
• Layer 5a (memex-kb): Migrates to Denote format
• Layer 7 (notes): Exports Denote org → markdown for publishing

Philosophy: Extends Anthropic's Life Sciences paradigm (domain context + AI = expert collaboration) from Biology research to personal knowledge work.

Performance Considerations

When working with 3,000+ files:

• Caching: Graph building is cached (10s first time, <1s after)
• Generators: Large searches use streaming (memory efficient)
• Timeouts: Long operations have configurable limits
• Pagination: Large result sets are paginated automatically

Troubleshooting

Links Not Resolving

• Check if file exists in specified silos
• Try partial match (first 8 chars of timestamp)
• Verify silo paths use os.path.expanduser()

Graph Building Slow

• First build takes ~10 seconds for 3,000 files (normal)
• Subsequent builds use cache (<1 second)
• Use incremental update for changed files only

Code Block Execution Fails

• Check :tangle path exists
• Verify code block language support
• Review :results option syntax

Encoding Errors

• All scripts use UTF-8
• Korean (한글) filenames fully supported
• File paths expanded with os.path.expanduser()

See Also

• Denote Package by Protesilaos Stavrou
• Org-mode documentation
• README.md in this repository for project context and Life Sciences paradigm connection