feat: improve lark im markdown guidance

[liujiashu-shiro]

Summary

Improve the --markdown vs --text guidance in the lark-im send/reply reference docs. Reposition --markdown as the recommended default for agents, add explicit selection rules, and reframe the docs around usage scenarios rather than caveats.

Changes

• Add a Default Selection Rule For Agents section providing clear, ranked guidance on when to use --markdown, --text, and --content
• Reorder the content flag comparison table to put --markdown first as the preferred default, and update descriptions from "what it does" to "when to use it"
• Rephrase --text vs --markdown guidance to be more concise and action-oriented
• Rename "Markdown Caveats" → "Markdown Boundaries" to soften framing, and reword the intro from negative ("does not send raw Markdown") to positive ("accepts Markdown-like input and converts")
• Move --markdown examples before --text examples in the Commands section to reinforce the new default preference
• Add a missing "wrong choice" item in Common Mistakes: choosing --text for headings, lists, links, or summaries when --markdown is the better fit
• Remove the standalone "When formatting does not need exact preservation" subsections; the content is merged into the main flow
• Unify the $'...' formatting tip to apply equally to both --markdown and --text

Test Plan

• No functional changes — docs-only PR, no tests required
• Manual review confirms the updated guidance is consistent across both send and reply reference pages

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Enhanced messaging content flag selection guidance with clear default rules for agents
  • Clarified distinction between text and markdown options with improved examples
  • Added details on markdown conversion, formatting boundaries, and normalization expectations
  • Updated best practices and common mistakes guidance

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9ca2c20a-709d-4e27-b2ec-9cf59f8756cd

📥 Commits

Reviewing files that changed from the base of the PR and between 98173ae and d26c5e1.

📒 Files selected for processing (2)

• skills/lark-im/references/lark-im-messages-reply.md
• skills/lark-im/references/lark-im-messages-send.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation for the Lark IM messages-send and messages-reply commands. Both reference files are restructured to clarify that --markdown converts input into Feishu post payloads with normalization, add a default flag selection table, introduce markdown boundaries guidance, and realign command examples and reference sections consistently.

Changes

Lark IM Message Content Flag Guidance Consolidation

Layer / File(s)	Summary
Default Selection Rule and markdown conversion behavior skills/lark-im/references/lark-im-messages-reply.md, skills/lark-im/references/lark-im-messages-send.md	Adds "Default Selection Rule For Agents" section with table mapping reply/message needs to --markdown, --text, --content, and media flags. Clarifies that --markdown converts Markdown-like input into Feishu post payloads with Feishu-specific normalization.
Markdown boundaries and content flag decision logic skills/lark-im/references/lark-im-messages-reply.md, skills/lark-im/references/lark-im-messages-send.md	Introduces "Markdown Boundaries" subsection stating --markdown is the simplest path for lightweight formatted content. Adds guidance for when --msg-type post --content or --content should be used for titles, multiple locales, cards, unsupported structures, and exact JSON control.
Message formatting preservation guidance skills/lark-im/references/lark-im-messages-reply.md, skills/lark-im/references/lark-im-messages-send.md	Revises "Preserving Formatting" instruction to recommend shell ANSI-C $'...' quoting when messages contain multiple lines, escaping, indentation, tabs, or backslashes, applicable to both --markdown and --text flags.
Command examples restructure skills/lark-im/references/lark-im-messages-reply.md, skills/lark-im/references/lark-im-messages-send.md	Adds "Commands" section header and restructures examples to show formatted --markdown example followed by plain --text one-liner, demonstrating updated guidance. Removes earlier "basic Markdown" examples from both files.
Parameter descriptions and common mistakes updates skills/lark-im/references/lark-im-messages-reply.md, skills/lark-im/references/lark-im-messages-send.md	Updates --text and --markdown parameter table entries with revised descriptions including internal conversion behavior. Revises "Common Mistakes" bullets to clarify --text vs --markdown selection and to state that --markdown is converted/normalized into Feishu post payload.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• larksuite/cli#893: Updates lark-im-messages-send.md and lark-im-messages-reply.md documentation for --markdown to clarify Feishu post conversion and markdown image constraints (pre-uploading img_xxx, no local paths).
• larksuite/cli#338: Implements segmented markdown payloads on blank-line separators (producing md + text placeholder nodes), which aligns with the markdown boundary behavior documented in this PR.

Suggested labels

domain/im, size/M

Suggested reviewers

• YangJunzhou-01
• liangshuo-1

Poem

🐰 A rabbit hops through docs with glee,
Clarifying flags for all to see—
Markdown boundaries now plain and bright,
Feishu posts converted just right!
--text and --markdown guide the way,
Happy agents post and reply today! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: improving Markdown guidance in lark-im documentation for the send/reply commands.
Description check	✅ Passed	The description covers all template sections with comprehensive detail on changes, clear motivation, and a test plan, though no related issues are listed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/im-markdown-choice

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@d26c5e1dea456abbdb782fb4b865fadee1f451c6

🧩 Skill update

npx skills add larksuite/cli#feat/im-markdown-choice -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.19%. Comparing base (bc8e9bd) to head (d26c5e1).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1237      +/-   ##
==========================================
- Coverage   69.21%   69.19%   -0.03%     
==========================================
  Files         633      637       +4     
  Lines       59563    59753     +190     
==========================================
+ Hits        41227    41345     +118     
- Misses      15015    15067      +52     
- Partials     3321     3341      +20     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.