14 KiB
14 KiB
Denote-Org Skills TODO
- Denote-Org Skills 0.1 Release Roadmap
- Implementation Notes
- Progress Tracking
- References
- Notes
Denote-Org Skills 0.1 Release Roadmap
DONE Project Setup
CLOSED: [2025-10-21 Tue 11:56]
- Create repository (~/repos/gh/orgmode-skills)
- README.md (English)
- README-KO.md (Korean)
- LICENSE (Apache 2.0)
- .gitignore
- Git init and first commit
- Git remote add origin
- Development log (docs/20251021T113500–*.org)
- Opus 4.1 feedback integration
TODO
Phase 1: Core Documentation [0/4]
SCHEDULED: <2025-10-21 Tue>
TODO SKILL.md - Main guide for Claude
Based on Opus 4.1 feedback, include:
-
When to use this skill (트리거 명확히)
- Denote PKM systems
- 3,000+ org files
- Knowledge graph navigation
- Literate programming
-
What this skill does
- Parse Denote filenames
- Resolve denote:ID links
- Build knowledge graph
- Execute code blocks
- Silo management
-
How to use effectively
- Quick start examples
- Python script usage
- Common workflows
-
Common pitfalls
- Edge cases (ID collision, circular refs, encoding…)
- Performance considerations
- Silo boundaries
Reference: PDF/XLSX SKILL.md structure
TODO denote-core.md - Denote specification
Content:
- File naming: YYYYMMDDTHHMMSS–title__tags.org
- Frontmatter: #+title, #+date, #+filetags, #+identifier
- Links: denote:TIMESTAMP
- Silo concept
- Real examples from 3,000+ files
TODO denote-silo.md - Silo management guide
Content:
- What is silo? (~/org/ vs ~/claude-memory/ vs ~/repos/*/docs/)
- Cross-silo links
- Priority resolution
- Path handling (os.path.expanduser)
TODO orgmode-base.md - Org-mode foundation
Content:
- Headings, properties, timestamps
- Code blocks (#+begin_src … #+end_src)
- Tables
- Links (file:, id:, denote:)
- Export basics
TODO
Phase 2: Denote Core Scripts [0/5]
SCHEDULED: <2025-10-22 Wed>
TODO scripts/denote_parser.py - File name and frontmatter parsing
Functions:
def parse_denote_filename(filename: str) -> dict:
"""
Parse: 20251021T105353--title__tag1_tag2.org
Returns: {
'timestamp': '20251021T105353',
'title': 'title',
'tags': ['tag1', 'tag2'],
'extension': 'org'
}
Edge cases:
- 한글 title handling
- No tags (filename without __)
- Multiple hyphens in title
"""
def parse_denote_frontmatter(content: str) -> dict:
"""
Parse org-mode frontmatter:
#+title:, #+date:, #+filetags:, #+identifier:
"""Implementation notes:
- Use os.path.expanduser() for paths
- Handle encoding (UTF-8)
- Validate timestamp format
- Test with 100+ real filenames
TODO scripts/denote_finder.py - File search with caching
Functions:
from functools import lru_cache
@lru_cache(maxsize=128)
def build_file_index(silo_path: str) -> dict:
"""Build index of all Denote files (cached)"""
def find_denote_file(identifier: str, silos: list) -> str:
"""Find file by timestamp ID"""
def find_by_tags(tags: list, silo: str) -> list:
"""Find files by tags"""
def find_by_date_range(pattern: str, silo: str) -> list:
"""Find files by date pattern (202510*)"""
def find_files_generator(pattern: str, silo: str):
"""Memory-efficient streaming search"""
for file in matching_files:
yield fileImplementation notes:
- Generator for large result sets
- lru_cache for index
- Support multiple silos
- Pattern matching (glob, regex)
TODO scripts/denote_links.py - Link resolution with fallback
Functions:
def resolve_denote_link(link_id: str, silos: list) -> str:
"""
Resolve [[denote:20251021T105353]] to file path
Try:
1. Exact match (full timestamp)
2. Fallback: partial match (first 8 chars)
3. Raise NotFoundError with suggestions
"""
def extract_denote_links(org_content: str) -> list:
"""Extract all [[denote:ID]] links from org file"""
def validate_links(filepath: str, silos: list) -> dict:
"""Check for broken links, return status"""Implementation notes:
- Error recovery (Opus feedback)
- Cross-silo links
- Backlinks tracking
TODO scripts/denote_silo.py - Silo management
Functions:
def find_in_silos(identifier: str, silos: list, priority: bool = True) -> str:
"""
Search in multiple silos
priority=True: return first match
priority=False: return all matches
"""
def list_silos(base_paths: list) -> list:
"""Discover all Denote silos"""
def get_silo_stats(silo_path: str) -> dict:
"""Get statistics: file count, tags, date range"""Implementation notes:
- os.path.expanduser()
- Symlink resolution
- Priority handling
TODO scripts/requirements.txt - Python dependencies
orgparse>=0.3.0
pypandoc>=1.11
pyyaml>=6.0
TODO
Phase 3: Knowledge Graph [0/2]
SCHEDULED: <2025-10-23 Thu>
TODO scripts/denote_graph.py - Graph builder with caching
Functions:
from functools import lru_cache
import networkx as nx
@lru_cache(maxsize=32)
def build_knowledge_graph(silo_path: str) -> nx.DiGraph:
"""
Build directed graph:
- Nodes: Denote files
- Edges: [[denote:ID]] links
- Attributes: tags, title, date
Cached for performance
"""
def get_connected_nodes(identifier: str, hops: int = 2) -> list:
"""Get connected files (N-hop neighbors)"""
def detect_circular_refs(graph: nx.DiGraph) -> list:
"""Detect circular references (Edge case!)"""
def update_graph_incremental(graph: nx.DiGraph, changed_files: list):
"""Incremental update (Opus suggestion)"""
def export_graph_stats(graph: nx.DiGraph) -> dict:
"""Export graph statistics (nodes, edges, clusters...)"""Implementation notes:
- Use networkx for graph operations
- Detect cycles (circular references)
- Incremental updates
- Performance monitoring (>1s warning)
TODO denote-knowledge-graph.md - Graph documentation
Content:
- Graph structure (nodes, edges)
- Algorithms (BFS, DFS for traversal)
- Circular reference handling
- Performance benchmarks (3,000+ files)
- Use cases (find related, clusters, orphans)
TODO
Phase 4: Org-mode Features [0/3]
SCHEDULED: <2025-10-24 Fri>
TODO scripts/org_parser.py - Org structure parsing
Functions:
import orgparse
def parse_org_file(filepath: str) -> orgparse.OrgNode:
"""Parse org file structure"""
def extract_headings(node: orgparse.OrgNode, level: int = None) -> list:
"""Extract headings (optionally by level)"""
def extract_properties(node: orgparse.OrgNode) -> dict:
"""Extract properties drawer"""
def extract_timestamps(node: orgparse.OrgNode) -> list:
"""Extract all timestamps"""
def extract_code_blocks(filepath: str) -> list:
"""Extract #+begin_src blocks with metadata"""TODO scripts/org_execute.py - Code block execution (Emacs compatible)
Functions:
def execute_org_blocks(filepath: str, block_names: list = None):
"""
Execute code blocks (org-babel compatible)
Support:
- :tangle option (file path)
- :results option (silent/output/value)
- Named blocks (#+name:)
- Languages (bash, python, ...)
Safety:
- Preserve org structure
- Update #+RESULTS blocks
- Error handling
"""
def tangle_org_file(filepath: str, output_dir: str = None):
"""Extract code blocks to files (:tangle)"""Implementation notes:
- Org-babel :results handling (Opus feedback)
- Structure preservation (critical!)
- Timeout handling
TODO scripts/org_export.py - Multi-format export
Functions:
import pypandoc
def export_to_markdown(org_file: str, output: str):
"""org → markdown (preserve Denote frontmatter)"""
def export_to_html(org_file: str, output: str):
"""org → HTML"""
def export_to_pdf(org_file: str, output: str):
"""org → PDF (requires LaTeX)"""
TODO
Phase 5: Testing & Examples [0/4]
SCHEDULED: <2025-10-25 Sat>
TODO tests/ - Test dataset structure
Create test files:
tests/ ├── small/ # 10 files (fast tests) │ ├── 20251021T100000--test-file-1__test.org │ ├── 20251021T100100--test-file-2__test_denote.org │ └── ... ├── medium/ # 100 files (feature tests) └── large/ # 1000+ files (performance tests)
Include edge cases:
- ID collision (same second)
- Circular references
- Cross-silo links
- 한글 titles
- Broken links
TODO examples/ - Usage examples
Create:
- examples/basic.org (basic Denote file)
- examples/literate.org (code blocks with :tangle)
- examples/knowledge-graph.org (multiple links)
TODO Run tests with 3,000+ real files
Test with actual ~/org/ directory:
- File finding speed
- Graph building time
- Link resolution accuracy
- Memory usage
TODO Performance benchmarks
Measure:
- denote_finder.py: <100ms for single file
- denote_graph.py: <10s for 3,000 files (cached: <1s)
- denote_links.py: <50ms per link
TODO
Phase 6: 0.1 Release [0/5]
SCHEDULED: <2025-10-26 Sun>
TODO Complete SKILL.md with all sections
Final review:
- All "When/What/How/Pitfalls" sections
- Working code examples
- Cross-references to other docs
TODO Update README with installation instructions
Add:
- Tested installation steps
- Dependencies verification
- Quick start that actually works
TODO Create CHANGELOG.md
Document:
- v0.1 initial release
- Features implemented
- Known limitations
TODO Final Git commit and tag
git add .
git commit -m "Release 0.1: Core Denote-Org Skills"
git tag -a v0.1 -m "Version 0.1: Denote core + org-mode base"
git push -u origin main
git push origin v0.1TODO Convert repository to Public
GitHub settings:
- Repository → Settings → General
- Danger Zone → Change visibility → Public
- Confirm
TODO
Phase 7: Community Outreach [0/4]
TODO Submit PR to awesome-claude-skills
Repository: https://github.com/travisvn/awesome-claude-skills
Add to Community Skills section:
### Knowledge Management
- **[denote-org](https://github.com/junghan0611/org-mode-skills)** -
Comprehensive Denote PKM system support with org-mode foundation.
Validated with 3,000+ files. Features knowledge graph navigation,
literate programming, and multi-silo management.TODO Share on communities
Platforms:
- Reddit r/emacs
- Reddit r/orgmode
- Hacker News
- Anthropic Discord/Forum
- Protesilaos Stavrou (Denote creator) - mention on Mastodon?
TODO Create announcement blog post
Write for notes.junghanacs.com:
- Title: "Denote-Org Skills: Life Sciences Paradigm for Life Everything"
- Content: Project vision, technical details, 9-layer context
- Publish as org → markdown
TODO AIONS Clubs announcement
Share with AIONS community:
- Project overview
- Life Sciences → Life Everything vision
- Contribution opportunity
Implementation Notes
Critical Requirements (from Opus 4.1)
File Path Handling
import os
# Always use
silo = os.path.expanduser("~/org/")Caching Strategy
from functools import lru_cache
@lru_cache(maxsize=128)
def expensive_operation():
passError Recovery
def resolve_with_fallback(identifier):
try:
return exact_match(identifier)
except NotFoundError:
return partial_match(identifier[:8])Performance Monitoring
def measure_performance(func):
# Log if > 1 second
passEdge Cases to Handle
- Denote ID collision (same second)
- Circular references in graph
- Cross-silo links
- 한글 encoding in filenames
- Symlink resolution
Dependencies
Python packages
- orgparse>=0.3.0
- pypandoc>=1.11
- pyyaml>=6.0
- networkx>=3.0 (for knowledge graph)
System
- Pandoc (for export)
- Python 3.8+
Progress Tracking
Week 1 (2025-10-21 ~ 2025-10-27)
- Day 1 (Mon): Project setup, README, Git init
- Day 2 (Tue): SKILL.md, denote-core.md
- Day 3 (Wed): Core scripts (parser, finder)
- Day 4 (Thu): Links, silo, graph
- Day 5 (Fri): Org-mode features
- Day 6 (Sat): Testing
- Day 7 (Sun): 0.1 Release
Metrics
Current Status (2025-10-21)
- Files: 5 (README×2, LICENSE, .gitignore, docs)
- Commits: 2
- Lines: 1,677 (docs: 829, README: 743, LICENSE: 202)
- Status: 🟡 Development
Target for 0.1
- Files: 15+ (docs, scripts, examples)
- Scripts: 7 Python files
- Tests: 3 levels (small/medium/large)
- Documentation: Complete
- Status: 🟢 Public Release
References
Anthropic Resources
- Official Skills Repository
- Agent Skills Engineering Blog
- document-skills/pdf/SKILL.md (8 scripts example)
- document-skills/xlsx/SKILL.md (CRITICAL rules example)
Denote Resources
Related Projects
Notes
Opus 4.1 Feedback Summary
"Life Sciences → Life Everything 패러다임 확장은 Anthropic Skills의 본질을 잘 이해한 접근입니다."
Key insights:
- SKILL.md structure is critical
- Performance optimization for 3,000+ files
- Edge case handling is essential
- Test dataset structure needed
Project Philosophy
Skills = Onboarding guide for domain expertise NOT a converter, AN operational system Validated with real-world 3,000+ files PKM
— Last updated: [2025-10-21 Tue 11:58]