memex/projects/org-json-bridge/docs/SKILL.md

name, description, homepage, metadata

name	description	homepage	metadata
org-json-bridge	Provides a bridge between Org-mode files and JSON for programmatic manipulation. Use when: needing to parse Org-mode to JSON, serialize JSON to Org-mode, or modify Org-mode files programmatically. NOT for: simple text edits, general Org-mode viewing, or direct human authoring.	https://docs.openclaw.ai/tools/skills/org-json-bridge	openclaw emoji requires primaryEnv 🌉 bins env python3 pip emacs

Org-JSON Bridge

This skill develops and utilizes an external tool to convert Org-mode files into a structured JSON representation, and vice-versa. This enables robust programmatic modification of Org-mode documents, addressing the limitations of direct string manipulation via the edit tool for complex structures like tables or source blocks. By working with a structured data model, it ensures consistent formatting and reliable updates.

When to Use

✅ USE this skill when:

• Modifying Org-mode file content programmatically (e.g., adding/removing table rows, updating flags in structured blocks).
• Converting Org-mode documents to a JSON representation for data processing.
• Converting structured JSON data back into Org-mode format.
• Encountering difficulties with the edit tool due to complex Org-mode formatting (e.g., tables, source blocks).

❌ DON'T use this skill when:

• Performing simple, single-line text edits in Org-mode files.
• Viewing or rendering Org-mode content (use a dedicated Org-mode client).
• Authoring Org-mode documents directly.
• Editing existing skills (use edit tool directly for SKILL.md files).

Instructions

This skill provides a Python script (org_bridge.py) that acts as a command-line interface to the Org-mode to JSON bridge.

1. Parse Org-mode to JSON (Command Line):

   org_bridge.py parse --file-path "path/to/my-doc.org" > output.json
   

2. Modify JSON (Internal Agent Logic):
   • The agent would then perform internal Python logic to load output.json, modify the JSON object (AST), and save the modified JSON to a new file, e.g., modified_data.json.
3. Render JSON to Org-mode (Command Line):

   org_bridge.py render --json-input-file "path/to/modified_data.json" --output-file "path/to/new-doc.org"
   

Commands

org_bridge.py parse

Parse an Org-mode file into a JSON representation and print to stdout.

# Example: Parse an Org-mode file to JSON
exec ~/.openclaw/workspace/skills/org-json-bridge/org_bridge.py parse --file-path "/home/amr/.openclaw/workspace/memex/5_projects/agora/agora-requirements-01-overview.org"

org_bridge.py render

Render a JSON representation back into an Org-mode file.

# Example: Render JSON back to an Org-mode file
# Assume 'modified_data.json' exists with the desired AST
exec ~/.openclaw/workspace/skills/org-json-bridge/org_bridge.py render --json-input-file "/path/to/modified_data.json" --output-file "/home/amr/.openclaw/workspace/memex/5_projects/agora/agora-requirements-01-overview.org"

Configuration

Environment variables needed:

• None directly for the bridge, but the underlying parser might have config.

Config values in openclaw.json:

• skill.org-json-bridge.parser_path - Path to the Python/Node.js script (if not directly in skill folder).

Notes

• Initial implementation will focus on core Org-mode elements needed for requirements documents (headings, lists, tables, source blocks).
• Requires installation of an Org-mode parsing library (e.g., orgparse for Python), though the Emacs Lisp handles the heavy lifting here.
• This skill is a foundational piece to enhance reliable document manipulation capabilities.