Feishu Md2blocks

Insert rich Markdown content (including tables) into Feishu documents. Use when feishu_doc write/append fails with tables, or when inserting complex formatte...

Security Scan

The skill mostly does what it says (converting Markdown to Feishu block inserts), but it silently reads local credentials from ~/.openclaw/openclaw.json without declaring that requirement — a scope/credential mismatch worth reviewing before installing.

Purpose & Capability

Skill name, description, and runtime behavior (convert Markdown → Feishu blocks and insert via block APIs) are coherent. The included script calls Feishu block conversion and descendant APIs as described.

Instruction Scope

SKILL.md does not mention that the runtime script will read Feishu app credentials from a local file (~/.openclaw/openclaw.json). The script requires access to this user config to request a tenant token — this is additional I/O and credential access not declared in the skill metadata or usage docs.

Install Mechanism

No install spec; skill is instruction-only with a Python script. Nothing is downloaded or installed by the registry. Risk from installation is low, but the included script will execute network calls at runtime.

Credentials

No required env vars or credentials are declared in the registry metadata, yet the script reads appId/appSecret from ~/.openclaw/openclaw.json to obtain a tenant_access_token. Accessing local config/credentials is sensitive and should be declared or made optional.

Persistence & Privilege

Skill does not request always:true or any special persistent privileges and does not modify other skills or system-wide settings. It only reads a user config file and calls Feishu APIs.

What to consider before installing

Inspect the script and your environment before using. Specifically: - The script reads Feishu app credentials from ~/.openclaw/openclaw.json (appId and appSecret) to obtain a tenant_access_token; this is not declared in the SKILL.md or registry metadata. Verify that file and its contents are what you expect. - If you do not want the skill to read your local config, either (a) run it in an isolated account/container where ~/.openclaw/openclaw.json is absent or contains a dedicated test app, or (b) modify the script to accept credentials via explicit environment variables/arguments and document that requirement. - Limit the Feishu app permissions to the minimum required (docx:document.block:convert and document edit scopes) and rotate credentials if you test with production tokens. - Confirm network targets: the script only calls official open.feishu.cn endpoints. If you see any different endpoints after your inspection, do not run the script. - Prefer explicit documentation: ask the publisher to update SKILL.md and registry metadata to declare the credential/config-file dependency so the requirement is transparent.

Feishu Markdown to Blocks

Insert Markdown content—including tables—into Feishu documents via the block convert + descendant API.

When to Use

• feishu_doc write replaces the entire document; use this to insert content at a position
• feishu_doc create_table_with_values has limitations for larger tables
• You need to insert tables, code blocks, or complex nested content into an existing doc

Usage

# Insert from file (appends to document end)
python3 <skill_dir>/scripts/md2blocks.py <doc_token> content.md

# Insert from stdin
echo "| A | B |\n|---|---|\n| 1 | 2 |" | python3 <skill_dir>/scripts/md2blocks.py <doc_token> -

# Insert after a specific block
python3 <skill_dir>/scripts/md2blocks.py <doc_token> content.md --after <block_id>

# Replace all content
python3 <skill_dir>/scripts/md2blocks.py <doc_token> content.md --replace

How It Works

1. Calls POST /docx/v1/documents/blocks/convert to convert Markdown → block structures
2. Removes merge_info from table blocks (read-only field that causes insertion errors)
3. Calls POST /docx/v1/documents/{doc}/blocks/{parent}/descendant to insert blocks

The descendant API handles nested structures (tables with cells containing text) that the simpler /children API cannot.

Position Control

The --after <block_id> option inserts content right after the specified block. The script finds the block's index automatically.

Key detail: The /descendant API's index parameter must be in the request body, not as a URL query parameter. Passing ?index=N in the URL is silently ignored (content appends to end). The script handles this correctly.

Supported Markdown

Text, headings (h1-h9), bullet lists, ordered lists, code blocks, quotes, tables, todo items, dividers.

Limitations

• Images in Markdown are not automatically uploaded; they require separate upload + patch steps
• Max 1000 blocks per insert call; split large documents if needed
• Requires docx:document.block:convert permission on the Feishu app
• Document edit rate limit: 3 ops/sec per document

Reference

For complete block-level API reference, see the feishu-block-ops skill which covers:

• All block APIs (create/read/update/delete/batch)
• Block type reference, text element types
• Table operation patterns (batch edit, merge cells)
• Common patterns and gotchas