docs: refine lark drive and markdown skills

[wittam-01]

Summary

Refines the lark-drive and lark-markdown skill docs based on the reviewed investigation. The update keeps the main skills focused on routing and critical decisions, moves detailed Drive rules into references, and syncs the Drive skill template to avoid regenerating the previous long structure.

Changes

• Add lark-markdown routing boundaries, identity guidance, zero-byte Markdown rationale, and regex GOOD/BAD examples.
• Rework lark-drive SKILL.md around key rules, identity routing, shortcuts, and explicit out-of-scope boundaries.
• Add Drive comments and permission reference docs, and add a shared Wiki token routing reference.
• Sync skill-template/domains/drive.md with the new Drive structure and remove the generic generated permission table block from skill-template/skill-template.md.

Test Plan

• node scripts/skill-format-check/index.js
• git diff --check
• bash scripts/check-doc-tokens.sh skills/lark-drive
• bash scripts/check-doc-tokens.sh skills/lark-markdown
• bash scripts/check-doc-tokens.sh skills/lark-shared
• Unit tests pass: not run because this is a docs/skill/template-only change with no Go code or CLI behavior changes.
• Manual local verification confirms the lark-cli flow works as expected: not run because no shortcut behavior or API call path changed.

Note: full bash scripts/check-doc-tokens.sh still fails on existing unrelated lark-wiki/lark-base reference examples containing realistic ou_ placeholders; those files are outside this PR scope.

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Rewrote Drive docs into a concise checklist with quick-decision routing and shortcut commands for common flows (search/import/upload/history/folder/title/wiki).
  • Added identity-routing guidance (when to act as user vs bot) and visibility/authorization tips.
  • Published detailed comments and permissions guides with query/ordering rules and common error remediation.
  • Clarified Markdown patch rules (no empty uploads) and refined templates and Wiki routing 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: cdd4c4ee-61df-4c1b-aefa-5dc54b08e9c0

📥 Commits

Reviewing files that changed from the base of the PR and between c90b85e and dd3811d.

📒 Files selected for processing (4)

• skill-template/domains/drive.md
• skill-template/skill-template.md
• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-comments-guide.md

✅ Files skipped from review due to trivial changes (1)

• skills/lark-drive/references/lark-drive-comments-guide.md

🚧 Files skipped from review as they are similar to previous changes (2)

• skill-template/skill-template.md
• skills/lark-drive/SKILL.md

---

📝 Walkthrough

Walkthrough

This PR consolidates and reorganizes Lark CLI skill documentation to improve clarity and user guidance. It restructures the Drive domain guide into a concise action-oriented format, introduces new reference guides for Drive permissions and comments, clarifies Markdown skill scope boundaries, and adds a shared Wiki token routing guide for the skill ecosystem.

Changes

Drive Documentation Ecosystem Rewrite

Layer / File(s)	Summary
Template restructuring and domain quick reference skill-template/skill-template.md, skill-template/domains/drive.md	The skill template no longer renders a permissions table in the actions block. The drive domain guide is rewritten from long-form narrative into condensed checklist-style sections: terminology clarification, "关键规则速览" and "快速决策" routing bullets mapping user intents to CLI commands and --type flags, a new "身份路由" table for --as user vs --as bot selection, and streamlined core concepts/comment/permission/delegation sections.
Drive skill main documentation skills/lark-drive/SKILL.md	The skill description is narrowed to emphasize cloud-storage management scope and explicitly list out-of-scope categories. The skill body adds "关键规则速览" and "快速决策" sections with routing rules for Wiki tokens (via drive +inspect), import type mappings (--type docx/sheet/slides/bitable), identity selection rules, and an expanded shortcuts table with behavioral notes for sync/push/status commands. Prior content including detailed token-format tables, extensive comment/query semantics, and API resource listings is removed and consolidated into new reference guides.
Drive permission and comment reference guides skills/lark-drive/references/lark-drive-permission-guide.md, skills/lark-drive/references/lark-drive-comments-guide.md, skills/lark-drive/references/lark-drive-reactions.md	New lark-drive-permission-guide.md documents permission application rules, public-permission error-code recovery (91009–91012), and bot self-authorization workflow. Expanded lark-drive-comments-guide.md provides comprehensive guidance on comment creation (full vs. partial), document-type-specific ID derivation, escaping rules, querying/statistics defaults, reply constraints, and batch vs. list-based traversal. The reactions guide is updated to reference the comments guide as a prerequisite.

Markdown & Cross-Skill Routing Clarifications

Layer / File(s)	Summary
Markdown skill documentation and identity policy skills/lark-markdown/SKILL.md	The skill description is refined to explicitly scope Markdown operations to Drive-native actions and exclude docx import (delegated to lark-drive). A new "身份策略" section defines --as user vs --as bot selection rules and guidance for CI/automation. The markdown +patch constraint is clarified: resulting content cannot be empty because Drive rejects 0-byte Markdown files. The shortcuts table is updated to reflect current command descriptions.
Markdown patch reference and regex examples skills/lark-markdown/references/lark-markdown-patch.md	The patch documentation explicitly notes Drive's 0-byte file rejection and the CLI's error-before-upload behavior. A new "GOOD / BAD：正则转义" section demonstrates correct regex escaping patterns, including how to escape parentheses/dots and use $$ for literal $ replacement output.
Wiki token routing guide skills/lark-shared/references/lark-wiki-token-routing.md	New shared reference documenting how to unwrap Lark Wiki /wiki/{token} URLs into underlying object types and canonical tokens using drive +inspect or manual lookup. Includes a routing table mapping obj_type values to appropriate skills and clarifies rules for correct token usage across the skill ecosystem.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#863: Adds Drive permission error-recovery guidance (91009–91012 codes) that this PR consolidates into the new permission reference guide.
• larksuite/cli#947: Adds lark-cli drive +inspect shortcut feature that this PR recommends for Wiki URL unwrapping.
• larksuite/cli#981: Related Drive comment guidance updates that overlap with the expanded comments guide in this PR.

Suggested labels

domain/ccm

Suggested reviewers

• fangshuyu-768
• liangshuo-1

Poem

🐰 I hopped through docs to tidy the trail,
Tokens routed true without a fail,
Comments and scopes in neat little rows,
Markdown and wiki where each pathway goes,
A rabbit's cheer — docs light as a sail!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: refine lark drive and markdown skills' clearly and specifically summarizes the main change: refining documentation for the lark-drive and lark-markdown skills.
Description check	✅ Passed	The PR description follows the required template with all sections completed: Summary (3 sentences explaining motivation and scope), Changes (4 bullet points detailing main changes), Test Plan (6 test items with clear status), and Related Issues (None).
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 docs/lark-drive-markdown-skills

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.17%. Comparing base (99e314f) to head (dd3811d).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1203      +/-   ##
==========================================
+ Coverage   69.14%   69.17%   +0.02%     
==========================================
  Files         630      630              
  Lines       59304    59380      +76     
==========================================
+ Hits        41005    41075      +70     
- Misses      14988    14996       +8     
+ Partials     3311     3309       -2     

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

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@skill-template/domains/drive.md`:
- Line 7: The two import bullets that currently map CSV/Excel ambiguously need
to be rewritten to be destination-driven: replace the mixed rule that says
“Excel / CSV / .base -> --type bitable” and the conflicting “.xlsx/.xls/.csv ->
--type sheet” with explicit pairs such as “导入为 bitable 请使用 --type bitable（示例:
.base, 或当目标是 Bitable 时）” and “导入为 sheet 请使用 --type sheet（示例: .xlsx, .xls,
.csv，当目标是 Sheet 表格时）”, and apply the same explicit destination-first wording to
the related bullets around the other occurrences so every file extension maps
only when the user’s intended destination (bitable vs sheet vs docx vs slides)
is specified.

In `@skills/lark-drive/SKILL.md`:
- Line 20: The doc has conflicting import mappings for Excel/CSV: one occurrence
maps Excel/CSV to "--type bitable" while another maps ".xlsx/.xls/.csv" to
"--type sheet"; pick the correct destination (e.g., decide Excel/CSV should map
to either "--type sheet" or "--type bitable"), then make both occurrences
consistent by updating the mapping strings and any explanatory text so Excel/CSV
always point to the chosen type, and ensure examples and the sentence that
starts with "本地文件导入为在线文档统一走 `drive +import`" reflect that single, unambiguous
rule.

🪄 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: 057b0c23-26ba-405b-948b-836ca0103ed7

📥 Commits

Reviewing files that changed from the base of the PR and between 0bdd7de and c90b85e.

📒 Files selected for processing (9)

• skill-template/domains/drive.md
• skill-template/skill-template.md
• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-comments-guide.md
• skills/lark-drive/references/lark-drive-permission-guide.md
• skills/lark-drive/references/lark-drive-reactions.md
• skills/lark-markdown/SKILL.md
• skills/lark-markdown/references/lark-markdown-patch.md
• skills/lark-shared/references/lark-wiki-token-routing.md

💤 Files with no reviewable changes (1)

• skill-template/skill-template.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#docs/lark-drive-markdown-skills -y -g