feishu-md2blocks

What This Skill Does

The feishu-md2blocks skill is a specialized tool designed to bridge the gap between simple text-based Markdown and the complex structural requirements of Feishu's Docx API. While native Feishu API endpoints for writing documents often replace the entire content or struggle with nested structures like tables, this skill leverages the Feishu /docx/v1/documents/blocks/convert endpoint. It processes Markdown inputs—converting them into valid block hierarchies—and then pushes them to specific locations within an existing document. By handling the conversion logic and technical nuances like removing read-only merge_info fields, it ensures that complex formatted content, such as tables, code blocks, and nested lists, are rendered correctly.

Installation

To add this skill to your OpenClaw environment, execute the following command in your terminal:

clawhub install openclaw/skills/skills/deadblue22/feishu-md2blocks

Ensure that your Feishu application has the docx:document.block:convert permission enabled in the Developer Console. This permission is mandatory for the skill to successfully translate Markdown into Feishu-native blocks.

Use Cases

• Complex Reporting: Automate the generation of status reports that contain data tables or code snippets and append them to an existing project document.
• Dynamic Documentation: Inject formatted documentation into onboarding guides or project wikis without wiping out existing content.
• API-Driven Content Generation: Integrate with data analysis tools to convert tabular results into professional-looking tables within a Feishu Doc.
• Structured Lists: Maintain complex nested lists or todo items across collaborative team documents automatically.

Example Prompts

1. "Insert the following table into my Q3-Report document after the executive summary section: [Paste Markdown table data]"
2. "Append the latest error log code block from the dev server to the bottom of the Feishu document token doc_abc123."
3. "Convert this Markdown list of team tasks and insert it after the block with ID 'blk_998877' in my project doc."

Tips & Limitations

• Rate Limits: Feishu enforces a limit of 3 operations per second per document. Avoid flooding the API if you are performing bulk updates.
• Image Handling: Images in Markdown are not automatically uploaded. They require a separate upload and patching sequence. This skill focuses on text, tables, and block-level formatting.
• Size Constraints: The API supports up to 1000 blocks per request. If your content is extremely large, break it down into smaller chunks.
• Positioning: Always ensure you have the correct block_id when using the --after flag. Incorrect IDs will default to appending at the end of the document.