---
name: org-json-bridge
description: "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."
homepage: https://docs.openclaw.ai/tools/skills/org-json-bridge
metadata: { "openclaw": { "emoji": "🌉", "requires": { "bins": ["python3", "pip", "emacs"], "env": [] }, "primaryEnv": "" } }
---

# 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):**
    ```bash
    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):**
    ```bash
    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.

```bash
# 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.

```bash
# 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.