--- 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**: ```org #+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 ```bash # 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:** ```bash # 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):** ```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:** ```bash # 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: `LEVELTITLE` - 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) ```bash # Not yet implemented - use glob/grep for now fd --type f "20251021T105353" ~/org/ ``` ### 4. Denote Link Resolution (🚧 Coming Soon) ```bash # 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 ```bash # 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 ```bash # 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) ```bash # 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](https://protesilaos.com/emacs/denote) by Protesilaos Stavrou - [Org-mode](https://orgmode.org/) documentation