docs(skills): default raw URLs for Lark Drive-native resource links

[nguyenngothuong]

What

Adds a shared link-writing rule to lark-shared/SKILL.md and references it from the Docx, Sheets, and Base write paths, so agents stop defaulting to [title](url) for Feishu/Lark Drive-native resource links.

Closes #1298.

Why

When agents write Feishu/Lark resource links (Docx, Sheets, Base/bitable, Wiki, Drive, Slides, Minutes) into rich content, raw URLs are the better default: the editor can convert them into native cards, previews, or @mentions. Wrapping them as Markdown [title](url) fixes them as plain hyperlinks and loses that conversion. The skills didn't state this, so agents had no reason to distinguish native resource URLs from external ones.

Changes

• lark-shared/SKILL.md — new "链接书写规则" section as the single owner of the rule: default raw URLs for Drive-native resources, with explicit exceptions (custom display text, external URLs, non-native share/download/callback pages, structured link/rich_text API fields).
• lark-doc/references/lark-doc-md.md & lark-doc-xml.md — Markdown/XML write guidance now tells agents not to default to [title](url) / <a href> for resource URLs, pointing to the shared rule.
• lark-sheets/SKILL.md — cell-type table notes that native resource links default to the plain-URL form rather than the {"type":"url",...} display-text object.
• lark-base/references/lark-base-cell-value.md — text/url guidance defaults native resource links to raw URL strings.
• Wiki is covered by the shared rule's resource list (no separate rich-content write path).

Acceptance (per #1298)

• Rule has one shared owner instead of being copied into every skill
• Docx Markdown/XML guidance tells agents not to default to [title](url)
• Sheets and Base preserve legitimate rich-link behavior for custom display text while defaulting native resource URLs to raw strings
• Wiki coverage explicit through shared guidance
• Local checks pass (scripts/skill-format-check, scripts/check-skill-wire-vocab.sh)

Summary by CodeRabbit

Documentation

• Updated link formatting guidelines for native Lark resources (Docx, Sheets, Base, Wiki, Drive, Slides, Minutes) to clarify that bare URLs should be used by default, with custom display text only when explicitly needed for external links or non-native resources.

[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: 5413fa06-4a1d-492d-bea2-b43e777edf8a

📥 Commits

Reviewing files that changed from the base of the PR and between e1af7e3 and 7bd0828.

📒 Files selected for processing (5)

• skills/lark-base/references/lark-base-cell-value.md
• skills/lark-doc/references/lark-doc-md.md
• skills/lark-doc/references/lark-doc-xml.md
• skills/lark-shared/SKILL.md
• skills/lark-sheets/SKILL.md

---

📝 Walkthrough

Walkthrough

This PR establishes a shared rule for writing Feishu/Lark native resource URLs (Docx, Sheets, Base, Wiki, Drive, Slides, Minutes) across all skill documentation. Native resource links now default to bare URLs instead of Markdown or display-text link wrappers, with explicit exceptions for custom text, external URLs, and API schema objects. The rule is centralized in shared documentation and referenced from document formatting and structured data skills.

Changes

Lark native resource link-writing rules

Layer / File(s)	Summary
Shared link-writing rule definition skills/lark-shared/SKILL.md	New "链接书写规则（飞书/Lark 资源 URL）" section defines the default behavior (bare URLs for native resources in rich-text contexts), explicit exceptions for custom display text, external URLs, non-native pages (share/download/callback), and API schema-specific link/rich_text object construction.
Document formatting guidance (Markdown and XML) skills/lark-doc/references/lark-doc-md.md, skills/lark-doc/references/lark-doc-xml.md	New "链接写法" subsections in both Docx Markdown and XML reference docs clarify that native resource links should not default to Markdown [title](url) or XML <a> wrappers; exceptions for external URLs and non-native pages are specified, with references to the shared rule.
Structured cell data guidance (Sheets and Base) skills/lark-sheets/SKILL.md, skills/lark-base/references/lark-base-cell-value.md	New clarifications state that native resource links in cell data default to plain URL strings rather than {"type":"url",...} objects; the object form is reserved for custom display text, external URLs, or non-native pages, with pointers to the shared link-writing rules.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• larksuite/cli#456: Documents Sheets cell type formatting requirements for URL-with-text and rich types to use object format, complementing this PR's default bare-URL guidance.
• larksuite/cli#1120: Adds guidance for generating direct block anchor URLs in Lark documents, extending native document link handling.

Suggested labels

domain/base, size/M

Suggested reviewers

• fangshuyu-768
• wittam-01
• kongenpei

Poem

🐰 A rabbit hops through docs so clear,
Bare URLs now reign here—
No markdown wraps for Lark's own kin,
Share the rule, let links begin!
From Sheets to Docs, the word goes through,
Native defaults, tried and true. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: establishing a default for raw URLs when writing Lark Drive-native resource links in documentation.
Description check	✅ Passed	The description comprehensively covers all required sections: Summary, Why, Changes, and acceptance criteria from issue #1298. It clearly explains motivation, scope, and implementation details.
Linked Issues check	✅ Passed	All objectives from #1298 are fully addressed: shared rule defined in lark-shared/SKILL.md [#1298], Docx guidance updated [#1298], Sheets/Base guidance updated [#1298], Wiki covered [#1298], and local checks passed [#1298].
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the shared link-writing rule and updating references across five documentation files as specified in #1298, with no extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch docs/skill-link-url-guidance-1298

---

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.}

[zgz2048]

base 现在 cell 输入推荐写成 [标题](url) 模式，并且目前不会对原生链接进行转换