feishu-doc-write_skill

Overview

This skill implements a Feishu (Lark) Document API writer that converts Markdown into Feishu Block structures and writes them to cloud documents. It handles Markdown conversion, manual Block construction for Feishu-specific features, and concurrency/order guarantees when creating document blocks. Use it to reliably sync articles, create structured documents, and author long-form content in Feishu.

How this skill works

The skill converts full Markdown into Feishu Block JSON either via the official Markdown->Blocks convert endpoint or by constructing Block JSON for features the converter does not support (callout, container blocks, images). It then writes blocks to a document using the Create Blocks API, preferring single-batch writes or serial indexed writes to preserve ordering. For container blocks (callout) and images it performs the required two-step creation and upload flows.

When to use it

• Syncing published articles or documentation to a Feishu document for collaboration or backup.
• Creating Feishu-native content that requires callouts, code blocks, images, lists, and headings.
• Importing long-form Markdown while preserving order and styling in Feishu.
• Batch-updating a document with many blocks where concurrent writes could break ordering.
• Generating structured reports or knowledge pages that rely on nested container blocks.

Best practices

• Convert the entire Markdown output first, then send a single batch create request when possible to guarantee order.
• For long documents split by H2/H3 and submit sequential batches with a small delay (200–500ms) between batches.
• Create container blocks (callout) and images with their two-step flows: create placeholder, then add children or upload media.
• Use separate Block entries for each list item — do not attempt to pack multiple items into one block.
• Cache and refresh tenant access tokens before expiry (tokens ~2 hours). Always use document_revision_id=-1 for writes.

Example use cases

• Automatic nightly export of a knowledge base in Markdown to a Feishu document for team review.
• Programmatic creation of playbooks with callouts and action items using custom callout markup.
• Migrating blog posts to Feishu while preserving headings, code fences, lists, and images.
• Building onboarding guides that require highlighted callouts and structured sections.
• Generating technical reports where code blocks need correct language enums for readability.