clarify lark-doc create title guidance

[fangshuyu-768]

Summary

• Clarify lark-doc create guidance for document title extraction: XML uses <title>, Markdown uses a leading unique # Title, and Markdown body sections should start at ##.
• Add the Markdown title rule to the lark-doc Markdown reference so agents avoid multiple H1 headings or H2-only documents that become Untitled.
• Add the matching XML title rule to the lark-doc XML reference so XML and Markdown guidance are both explicit.

Tests

• Not run (skill documentation-only change).

Summary by CodeRabbit

• Documentation
  • Enhanced documentation with clarified title formatting requirements for Markdown and XML document creation
  • Specified that Markdown documents require a single leading H1 heading for the title, with content starting from H2 onwards
  • Defined that XML documents require exactly one <title> element per document
  • Expanded best practices guidance to prevent title duplication within document content

[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: 20ef21c6-8630-4800-ba40-bea818e9aa8e

📥 Commits

Reviewing files that changed from the base of the PR and between 261fa38 and 1f12fc0.

📒 Files selected for processing (3)

• skills/lark-doc/references/lark-doc-create.md
• skills/lark-doc/references/lark-doc-md.md
• skills/lark-doc/references/lark-doc-xml.md

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

• skills/lark-doc/references/lark-doc-xml.md
• skills/lark-doc/references/lark-doc-create.md
• skills/lark-doc/references/lark-doc-md.md

---

📝 Walkthrough

Walkthrough

Three skill reference documentation files for the docs +create command are updated to specify title formatting rules: Markdown documents must use a single leading H1 as the title with body content starting at H2, and XML documents must contain exactly one <title> element.

Changes

Title Formatting Rules for docs +create

Layer / File(s)	Summary
Title constraints for Markdown and XML formats skills/lark-doc/references/lark-doc-create.md, skills/lark-doc/references/lark-doc-md.md, skills/lark-doc/references/lark-doc-xml.md	lark-doc-md.md adds a new 文档标题 subsection requiring a single # 标题 H1 at document start with subsequent headings at ##+. lark-doc-xml.md adds a 创建文档标题 subsection enforcing exactly one <title> element. lark-doc-create.md updates both the format-selection description and best-practices section to reflect these constraints and prohibit multiple H1s or title repetition in body.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• SunPeiYang996

Poem

🐇 A rabbit hops through docs so neat,
One H1 title, can't repeat!
XML gets a <title> too,
H2 and beyond for all the rest of you.
The lark flies high with rules so clear,
No duplicate headings allowed here! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: clarifying lark-doc create title guidance across XML and Markdown formats with specific rules.
Description check	✅ Passed	The description covers Summary and Changes sections matching the template structure. However, the Test Plan section is incomplete with only a note instead of the required checkbox format.
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 clarify-doc-create-title-guidance

---

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 73.39%. Comparing base (6217bd2) to head (1f12fc0).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1474   +/-   ##
=======================================
  Coverage   73.39%   73.39%           
=======================================
  Files         750      750           
  Lines       69288    69290    +2     
=======================================
+ Hits        50851    50853    +2     
  Misses      14695    14695           
  Partials     3742     3742           

☔ View full report in Codecov by Harness.
📢 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]

🧹 Nitpick comments (1)

shortcuts/doc/docs_create_test.go (1)

20-45: ⚡ Quick win

Exercise the mounted DocsCreate help output here.
v2CreateFlags() only checks the helper strings; it won’t catch a regression in the public docs +create --help wiring if DocsCreate.Flags stops including these flags. If the goal is to lock the user-visible contract, mount the command and assert the rendered help instead. Based on the DocsCreate wiring in shortcuts/doc/docs_create.go.

🤖 Prompt for 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.

In `@shortcuts/doc/docs_create_test.go` around lines 20 - 45, The test
TestDocsCreateV2HelpMentionsTitleRules currently only validates flag
descriptions from the v2CreateFlags() helper function directly, which won't
catch regressions if the DocsCreate.Flags wiring in shortcuts/doc/docs_create.go
stops including these flags in the actual command. To properly lock the
user-visible contract, mount the DocsCreate command and assert the rendered help
output (what users see when running docs +create --help) instead of checking the
flag helper strings directly.

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

Nitpick comments:
In `@shortcuts/doc/docs_create_test.go`:
- Around line 20-45: The test TestDocsCreateV2HelpMentionsTitleRules currently
only validates flag descriptions from the v2CreateFlags() helper function
directly, which won't catch regressions if the DocsCreate.Flags wiring in
shortcuts/doc/docs_create.go stops including these flags in the actual command.
To properly lock the user-visible contract, mount the DocsCreate command and
assert the rendered help output (what users see when running docs +create
--help) instead of checking the flag helper strings directly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d3cf8428-4da6-4e4e-a704-6b39e2a0ef71

📥 Commits

Reviewing files that changed from the base of the PR and between 6217bd2 and bc37219.

📒 Files selected for processing (4)

• shortcuts/doc/docs_create_test.go
• shortcuts/doc/docs_create_v2.go
• skills/lark-doc/references/lark-doc-create.md
• skills/lark-doc/references/lark-doc-md.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#clarify-doc-create-title-guidance -y -g