What does feishu-doc-style do?
Rules to follow when writing Feishu documents — applicable to technical proposals, PRDs, postmortems, and explanations. The only goal: make it readable in one pass.
When to Use
Whenever you are writing, editing, reviewing, or polishing a Feishu document or technical document, apply this rule set by default — no need to wait for the user to ask.
When the user explicitly types /feishu-doc-style or asks "Is this clear?" or "How do I make this understandable?", review against the Core Principles and Pre-Submission Checklist and suggest edits.
When helping someone revise a draft, first scan through the checklist item by item, flag violations, provide the corrected version, then explain what was changed.
Core Principles
-
Keep only conclusions — omit reasoning. Delete derivation processes like "Why we chose this" or "How we weighed tradeoffs." Give the conclusion directly. The reader wants the answer, not your thought process.
-
Keep paragraphs to two or three lines. Do not pile many sentences into one large paragraph. Long paragraphs tire the reader.
-
Use diagrams for flow content — not text. For sequence, data flow, or state changes, use a diagram instead of a long textual description. A sequence diagram is worth a paragraph of text.
-
Arrows only appear in diagrams. Do not write arrow chains like "A → B; C → D" in body text or tables. This forces the reader to reverse-lookup in their head, shifting the translation cost onto them.
-
Speak plainly — no jargon. If the reader won't understand internal terminology, replace it with plain language or explain it in one sentence when first used. See
references/jargon.mdfor common jargon replacements. -
Table cells contain complete short sentences. Do not pile abbreviations in cells — write "who did what and what the result was."
-
No decorative emojis or callout boxes. Emojis like 📌 ⭐ 🔒 💡 ✅ 🚧, and colored callout boxes, make the page look messy and cluttered. For emphasis, use "Bold mini-heading. followed by body paragraph" in a regular paragraph; for document-level notes or status prompts, use
>blockquotes. Throughout the whole document, there should not be a single decorative emoji or callout box. -
Use bold sparingly. At most one or two per section, and only on truly global conclusions or principle leads. Do not bold noun lists, field names, or directional words (left/middle/right) — hierarchy is expressed through sentence structure and table structure, not by splashing bold everywhere.
-
Do not use characters that cannot be typed on a keyboard. Circled numbers ①②③④⑤, status emoticons ✓ ◐ ◑ ● ○, icons like
!, or functional icons ⚡ ⌘ — these are not things people normally type and look like "copy-pasted from the UI." Use normal ordered lists "1. 2. 3." or "first, second"; for statuses write "Completed / In Progress"; for steps use normal numbers (Step 1 / STEP 1). -
Headings describe content — not structure. Headings should directly state what this section is about ("This year's goals and main measures" / "What's being done and progress"), not insert organizational logic or scaffolding. Do not write structural prefixes like "Summary:", "Details:", "Part 1:" — overall vs. parallel vs. sequential is naturally expressed through content order and heading hierarchy. Also do not add meta-explanations in headings (e.g., "(AI appends daily)" — put that in the body or a
>blockquote). Also avoid forcing content into a mismatched frame — for example, cramming "several tasks grouped by direction" into a time-based shell like "Progress in H1"; first think clearly about the real organizational dimension of this content (current state by direction, flow by time). Self-check: when you read the heading aloud, does it sound like a normal person would name it? "Summary: This year's goals" does not; "This year's goals" does.
How to Write Tables
Column names should be in plain language, ideally phrased as questions. For example, "What the user does / What the system does in the background / Whether it's synchronous" — not internal jargon like "Sync entry / Async link & persistence."
Cells contain complete short sentences — one sentence explaining who did what and what the result was.
Put technical details in the main body text. The table is only for comprehension. Full DDL, interface definitions, etc., go in dedicated sections in the body; do not cram them into the table.
Diagrams: Which Type When
For any process that can be drawn as a diagram, do not use text. Choose the diagram type based on what you want to express:
| What to Express | Which Diagram to Use |
|---|---|
| Logic flow, sequence, step-by-step data flow | Sequence diagram (mermaid sequenceDiagram), with lanes by role |
| Module hierarchy, dependencies | Architecture diagram (card-style nodes: icon + title + one-line explanation, color-coded by layer) |
| State transitions (e.g., draft → published → deprecated) | Flowchart or state diagram (mermaid flowchart) |
See references/feishu-tooling.md for how to actually insert these diagrams into Feishu (mermaid board, lark-whiteboard, lark-cli).
Pre-Submission Checklist
Before submitting, go through this checklist item by item. If any item fails, go back and fix it:
- No arrow chains (A → B) in body text or tables? Arrows only appear in diagrams?
- No paragraph exceeds two or three lines?
- No unexplained jargon? Every term given a plain-language explanation when first used?
- Flow content expressed as diagrams, not piled into text?
- Table cells contain complete short sentences? Column names are plain language?
- Deleted long reasoning about "Why we chose this" — only conclusions left?
- No decorative emojis, no colored callout boxes? Emphasis via bold mini-headings, notes via blockquotes?
- No circled numbers ①②③, status emoticons ✓ ◐, or other keyboard-untypable characters?
- Bold used sparingly — at most one or two global conclusions per section, no bold on noun lists / directional words?
- Headings and tables do not have bare English words as subjects? Design mock English terms have Chinese annotations in parentheses?
- Headings directly name the content — no structural prefixes like "Summary:/Details:/Part 1:" or meta-explanations? No content forced into a mismatched time-based shell?
Companion References
references/jargon.md: Jargon replacement table — always replace the left column with the right column's plain language; continuously updated.references/feishu-tooling.md: Cheat sheet for how to insert diagrams into Feishu (mermaid board, lark-whiteboard, lark-cli).
This Skill Follows Its Own Rules
This skill's SKILL.md, README, and references are all written according to the rules above. When modifying this skill, first treat the "Pre-Submission Checklist" as a self-check: no decorative emojis, no arrow chains, short paragraphs, headings describe content. If the rules change, update both SKILL.md and README synchronously — do not let them diverge.