docs(skills): clarify Drive-native resource URL guidance

[Zhang-986]

Summary

Clarifies skill guidance for writing Feishu / Lark Drive-native resource URLs into docs, sheets, base fields, and wiki content.

Drive-native URLs should stay as raw URL strings by default so Lark editors and APIs can preserve native resource behavior instead of forcing Markdown-style display text.

Changes

• Add shared Drive-native resource URL guidance in lark-shared.
• Reference the shared rule from doc, sheets, base, and wiki skills.
• Update detailed Markdown/XML/Base cell-value and Sheets write-cells references to keep default behavior consistent across skills.

Test Plan

• node scripts/skill-format-check/index.js
• git diff --check
• make unit-test blocked locally by Go 1.26 race-test startup SIGSEGV across unrelated packages before exercising this docs-only change.

Related Issues

• Fixes Improve skill guidance for writing Lark resource URLs #1298

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR establishes and documents a consistent rule for writing Lark Drive-native resource URLs across all skills: default to raw URL strings without Markdown or link formatting, except when users explicitly request custom display text or target APIs require structured link objects.

Changes

Drive-native resource URL writing rules

Layer / File(s)	Summary
Shared resource URL writing rule definition skills/lark-shared/SKILL.md	New section defining the shared rule: default to raw opaque URL strings for Drive-native resources (Docx, Sheets, Base, Wiki, Drive files/folders, Slides, Minutes), prohibit URL rewriting/encoding/query modification, and enumerate exceptions for custom display text and structured API fields.
Skill-specific resource URL documentation skills/lark-base/SKILL.md, skills/lark-base/references/lark-base-cell-value.md, skills/lark-doc/SKILL.md, skills/lark-doc/references/lark-doc-md.md, skills/lark-doc/references/lark-doc-xml.md, skills/lark-sheets/SKILL.md, skills/lark-sheets/references/lark-sheets-cell-data.md, skills/lark-wiki/SKILL.md	Updates Base, Sheets, Docx, and Wiki skill docs to reference the shared rule. Base and Sheets clarify raw URL defaults for cell values, with structured object format only when custom display text is explicitly requested. Docx guides both Markdown and XML paths to preserve raw URL defaults. Wiki documents the rule for node and backing Docx content.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• larksuite/cli#456: Both PRs update skills/lark-sheets/SKILL.md to document how Feishu/Lark Drive resource URLs should be represented in cell-value writing (main PR: default raw URL string except when custom display/structured rich link is required; retrieved PR: specifies special URL-related cell kinds require object format, e.g., URL-with-text).

Suggested labels

domain/base, size/M

Suggested reviewers

• fangshuyu-768
• wittam-01

Poem

🐰 URLs in Drive don't need their brackets bound,
Raw strings tell the story—no Markdown sound,
Just link when the user asks for a name,
Native cards and previews reward this game! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(skills): clarify Drive-native resource URL guidance' is concise and accurately summarizes the main change—clarifying guidance for writing Drive-native resource URLs across skills.
Linked Issues check	✅ Passed	The PR fully addresses issue #1298's coding requirements: centralizes Drive-native resource URL guidance in lark-shared, references it from multiple skills, updates reference documentation, and ensures local checks pass.
Out of Scope Changes check	✅ Passed	All changes are narrowly scoped to adding and referencing Drive-native resource URL guidance across skill documentation files with no unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description aligns well with the repository's template, including summary, changes list, test plan with checkboxes, and related issues link.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR standardizes guidance across Lark/Feishu skills docs for writing Drive-native resource URLs, introducing a shared “resource URL write rules” section and referencing it from Wiki/Docs/Sheets/Base documentation to avoid incorrectly converting URLs into titled links.

Changes:

• Added a canonical “资源 URL 写入规则” section to lark-shared/SKILL.md.
• Referenced the shared rule from Wiki, Docs (Markdown/XML), Sheets, and Base skill/reference docs.
• Minor markdown cleanup (removed trailing blank line).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
skills/lark-wiki/SKILL.md	Adds reference to shared resource-URL writing rule for Wiki content
skills/lark-sheets/references/lark-sheets-cell-data.md	Documents URL-writing behavior for +write and +append
skills/lark-sheets/SKILL.md	Adds a rule block clarifying how to represent Drive-native URLs in cells
skills/lark-shared/SKILL.md	Introduces canonical “资源 URL 写入规则” section
skills/lark-doc/references/lark-doc-xml.md	Adds XML-specific guidance referencing shared rule
skills/lark-doc/references/lark-doc-md.md	Adds Markdown-specific guidance referencing shared rule
skills/lark-doc/SKILL.md	Adds global rule block for Docs content URL writing
skills/lark-base/references/lark-base-cell-value.md	Adds guidance for writing Drive-native URLs in Base field values
skills/lark-base/SKILL.md	Adds Base-wide guidance referencing shared rule

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/lark-doc/SKILL.md`:
- Around line 30-31: The blockquote in SKILL.md currently contains an internal
blank line triggering markdownlint MD028; edit the blockquote (the paragraph
starting with "**资源 URL 写入规则：** 文档内容中写入飞书 / Lark Drive-native 资源 URL 时...") to
remove the blank line so the quote is contiguous and no empty lines exist inside
the blockquote, ensuring the block follows MD028 (no-blanks-blockquote).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9d72a49e-48a6-414d-8f82-358f0e96b663

📥 Commits

Reviewing files that changed from the base of the PR and between 7c50b3d and 00db7e2.

📒 Files selected for processing (9)

• skills/lark-base/SKILL.md
• skills/lark-base/references/lark-base-cell-value.md
• skills/lark-doc/SKILL.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
• skills/lark-sheets/references/lark-sheets-cell-data.md
• skills/lark-wiki/SKILL.md