Feishu Docs Writing Skill

Create or update Feishu Cloud Docs using Markdown as the intermediate format. Supports automatic conversion of Mermaid/PlantUML diagrams to Feishu Boards.

Prerequisite: Complete authentication before use:
feishu-cli auth login
(OAuth login, it is recommended to include the
offline_access
scope to obtain a 30-day valid Refresh Token).

Quick Creation of Blank Document

The simplest way to create a new Feishu Cloud Document:

bash

feishu-cli doc create --title "Document Title" --output json

After creation, you must immediately:

Grant

full_access

permission:

bash

feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access --notification

Transfer document ownership:

bash

feishu-cli perm transfer-owner <document_id> --doc-type docx --member-type email --member-id user@example.com --notification

Send a Feishu message to notify the user that the document has been created

Core Concepts

Markdown as Intermediate Format: Conversion between local documents and Feishu Cloud Documents is done via Markdown format, with intermediate files stored in the

/tmp

directory.

CRITICAL: Full overwrite of existing documents is PROHIBITED
Absolutely forbidden to use
doc import --document-id <id>
to fully overwrite existing documents! This will:
Lose all inline comments

Break board/whiteboard references (become empty placeholder blocks)

Lose manually edited formats and content from users
Incremental updates must be used for updating existing documents:
doc add
(append),
doc update
(modify blocks),
doc delete
(delete blocks).
doc import --document-id
is only allowed when the user explicitly requests full replacement.

Usage

bash

# Create new document
/feishu-write "Document Title"

# Update existing document
/feishu-write <document_id>

Execution Flow

Create New Document

Collect Content
- Confirm the document title with the user
- Collect content provided by the user or generate content based on the conversation
Generate Markdown
- Create a Markdown file at
```
/tmp/feishu_write_<timestamp>.md
```
- Use standard Markdown syntax

Import to Feishu

bash

feishu-cli doc import /tmp/feishu_write_<timestamp>.md --title "Document Title"

Add Permissions (optional, grant full_access to specified users)
```
full_access
```
is the highest permission, including: managing collaborators, editing content, managing document settings (copy/move/delete), viewing historical versions, exporting, and all other capabilities.
bash
```
feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access
```
Notify User
- Provide the document link
- Send a Feishu message notification

Update Existing Document (Incremental Update)

Principle: Only modify the parts that need to be changed, leaving the rest of the content intact.

Scenario A: Append Content to the End of the Document

The most common scenario. Directly use

doc add

to append in Markdown format:

bash

# 1. Prepare the content to append (only write the new part, do not include existing content)
cat > /tmp/feishu_append.md << 'EOF'
## New Section Title

New content...
EOF

# 2. Append to the end of the document
feishu-cli doc add <document_id> /tmp/feishu_append.md --content-type markdown

Scenario B: Insert Content at a Specified Position in the Document

bash

# 1. Get the document block structure and find the insertion point
feishu-cli doc blocks <document_id>

# 2. Insert at the specified position under the parent block
feishu-cli doc add <document_id> /tmp/feishu_insert.md \
  --content-type markdown \
  --block-id <parent_block_id> \
  --index <position>

Scenario C: Modify Content of an Existing Block

bash

# 1. Get the document block structure and find the block_id to modify
feishu-cli doc blocks <document_id>

# 2. Update the specified block
feishu-cli doc update <document_id> <block_id> \
  --content '{"update_text_elements":{"elements":[{"text_run":{"content":"Updated text"}}]}}'

Scenario D: Delete Blocks in a Specified Range

bash

# Delete child blocks from index 2~4 under the parent block
feishu-cli doc delete <document_id> <parent_block_id> --start 2 --end 5

# Delete all child blocks under the parent block
feishu-cli doc delete <document_id> <parent_block_id> --all

Scenario E: Replace a Section

First delete the blocks of the old section, then insert new content at the same position:

bash

# 1. Get the block structure and locate the block range of the section
feishu-cli doc blocks <document_id>

# 2. Delete the old section (assuming it is at indexes 5~8 under the parent block)
feishu-cli doc delete <document_id> <parent_block_id> --start 5 --end 9 -f

# 3. Insert new content at the same position
feishu-cli doc add <document_id> /tmp/feishu_new_section.md \
  --content-type markdown \
  --block-id <parent_block_id> \
  --index 5

When is full overwrite allowed: Only when the user explicitly says "rewrite the entire document" or "full replacement", can
feishu-cli doc import /tmp/file.md --document-id <id>
be used. Incremental updates are required by default.

Supported Markdown Syntax

Syntax	Feishu Block Type	Description
`# Heading`	Heading1-6
`Plain text`	Text
`- List item`	Bullet	Supports indentation nesting
`1. Ordered item`	Ordered	Supports indentation nesting
`- [ ] Task`	Todo
```code```	Code
```mermaid```	Board	Recommended
```plantuml``` / ```puml```	Board	PlantUML diagrams
`> Quote`	QuoteContainer	Supports nested quotes
`> [!NOTE]` etc.	Callout	6 types
`---`	Divider
`Bold`	Bold style
`Italic`	Italic style
`~~Strikethrough~~`	Strikethrough style
`<u>Underline</u>`	Underline style
`Inline code`	Inline code style
$Formula$	Inline Formula	Supports multiple formulas in one paragraph
`$$Formula$$`	Block Formula	Independent formula line
`[Link](url)`	Link
`	Table	`

Recommendation: Use Mermaid / PlantUML for Diagramming

When creating diagrams in documents, it is recommended to use Mermaid (PlantUML is also supported), which will be automatically converted to Feishu Boards.

Supported Mermaid diagram types:

✅ flowchart (supports subgraph)
✅ sequenceDiagram
✅ classDiagram
✅ stateDiagram-v2
✅ erDiagram
✅ gantt
✅ pie
✅ mindmap

Mermaid Restrictions (Must Be Followed, Otherwise Import Will Fail):

❌ Do not use
```
{}
```
curly braces in flowchart node labels (e.g.,
```
{version}
```
), as this will trigger parsing errors
❌ Do not use
```
par...and...end
```
syntax, which is not supported by the Feishu parser at all
❌ Avoid excessive complexity: 10+ participants + 2+ alt blocks + 30+ long message labels will trigger a server 500 error
✅ Safety threshold: participants ≤ 8, alt ≤ 1, message labels as short as possible
✅ Alternative to
```
par
```
: Use
```
Note over X: Execute in parallel...
```
instead
✅ Diagrams that fail to import will be automatically downgraded to code blocks for display, and content will not be lost

Example:

markdown

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
```

markdown

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

Callout Highlight Blocks

Create Feishu highlight blocks using Callout syntax in documents:

markdown

> [!NOTE]
> Tip information.

> [!WARNING]
> Warning information.

> [!TIP]
> Tip information.

> [!CAUTION]
> Warning information.

> [!IMPORTANT]
> Important information.

> [!SUCCESS]
> Success information.

Callouts support multi-line text and child blocks (such as lists).

Formulas

markdown

Inline formula: Area of a circle $S = \pi r^2$, circumference $C = 2\pi r$.

Block formula:
$$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

Advanced Operations

Add Board

Add a blank board to the document:

bash

# Add a board to the end of the document
feishu-cli doc add-board <document_id>

# Add a board at a specified position
feishu-cli doc add-board <document_id> --parent-id <block_id> --index 0

Add Callout

Add a highlight block to the document:

bash

# Add an info-type Callout
feishu-cli doc add-callout <document_id> "Tip content" --callout-type info

# Add a warning-type Callout
feishu-cli doc add-callout <document_id> "Warning content" --callout-type warning

# Add at a specified position
feishu-cli doc add-callout <document_id> "Content" --callout-type error --parent-id <block_id> --index 0

Callout Type and Color Mapping:

Feishu Callouts have 6 colors in total. Markdown import (

doc import

) supports all 6 types using the

[!TYPE]

syntax, while CLI commands (

doc add-callout --callout-type

) support 4 of them:

Color	Background Color Value	Markdown Syntax	CLI `--callout-type`
Blue	6	`[!NOTE]`	`info`
Red	2	`[!WARNING]`	`error`
Orange	3	`[!CAUTION]`	—
Yellow	4	`[!TIP]`	`warning`
Green	5	`[!SUCCESS]`	`success`
Purple	7	`[!IMPORTANT]`	—

When orange (CAUTION) or purple (IMPORTANT) is needed, please use the Markdown import method (
doc import
or
doc add --content-type markdown
).

Batch Update Blocks

Batch update block content in the document:

bash

# Batch update from JSON file
feishu-cli doc batch-update <document_id> --source-type content --file updates.json

JSON format example:

json

[
  {
    "block_id": "block_xxx",
    "block_type": 2,
    "content": "Updated text content"
  }
]

Output Format

After creation/update is completed, report:

Document ID
Document URL:
```
https://feishu.cn/docx/<document_id>
```
Operation status

Examples

bash

# Create new meeting minutes
/feishu-write "2024-01-21 Weekly Meeting Minutes"

# Update existing document
/feishu-write <document_id>

Frequently Asked Questions

Problem	Cause and Solution
Mermaid diagram import failed	The diagram will be automatically downgraded to a code block for display, and content will not be lost. Check if unsupported syntax such as `{}` curly braces or `par...and...end` is used
Permission addition failed	Check if the App in the Feishu Open Platform has been configured with the `docs:permission.member:create` permission and the application has been published
Authentication expired (401 error)	Re-execute `feishu-cli auth login` , it is recommended to include the `offline_access` scope to obtain a 30-day Refresh Token
Document created successfully but cannot be accessed	Confirm that `perm add` has been executed to grant `full_access` permission and `perm transfer-owner` has been executed to transfer ownership
Table content is not fully displayed	The Feishu API limits a single table to 9 rows and 9 columns, and excess parts will be automatically split into multiple tables, which is normal behavior

feishu-cli-write

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Docs Writing Skill

Quick Creation of Blank Document

Core Concepts

Usage

Execution Flow

Create New Document

Update Existing Document (Incremental Update)

Scenario A: Append Content to the End of the Document

Scenario B: Insert Content at a Specified Position in the Document

Scenario C: Modify Content of an Existing Block

Scenario D: Delete Blocks in a Specified Range

Scenario E: Replace a Section

Supported Markdown Syntax

Recommendation: Use Mermaid / PlantUML for Diagramming

Callout Highlight Blocks

Formulas

Advanced Operations

Add Board

Add Callout

Batch Update Blocks

Output Format

Examples

Frequently Asked Questions