Summary
Clarify the lark-doc Skill guidance for mathematical formulas so AI agents do not write Markdown/LaTeX delimiters as literal text when the document command is using the default XML format.
Problem
lark-cli docs +create and docs +update default to --doc-format xml. The XML reference currently lists <latex>E = mc^2</latex> in the inline-component table, but the format-dependent rule is easy to miss.
As a result, an agent may generate content such as:
<p>The result is $E = mc^2$.</p>
<p>$$\sum_{i=1}^{n} i$$</p>
In XML mode, $...$, $$...$$, \(...\), and \[...\] are ordinary text. They can therefore appear verbatim in the Feishu/Lark document instead of becoming native formula nodes.
The correct XML is:
<p>The result is <latex>E = mc^2</latex>.</p>
<p><latex>\sum_{i=1}^{n} i</latex></p>
Markdown writes are different: $...$ is valid only when the command explicitly uses --doc-format markdown.
Proposed Change
Update the existing lark-doc Skill rather than adding a duplicate Skill:
- Add a formula-routing rule to
skills/lark-doc/SKILL.md.
- Add a dedicated formula section to
references/lark-doc-xml.md covering:
- conversion from
$...$, $$...$$, \(...\), and \[...\] to <latex>...</latex>;
- inline versus standalone-paragraph examples;
- XML escaping for
&, <, and > inside formulas;
- avoiding
<pre> / <code> for formulas;
- relative
@file input for content containing $ and backslashes.
- Add matching Markdown guidance to
references/lark-doc-md.md.
- Recommend a post-write
docs +fetch --doc-format xml --detail full check to verify that the content contains <latex> nodes rather than literal delimiters.
Acceptance Criteria
- The Skill clearly distinguishes XML formula syntax from Markdown formula syntax.
- Agents are explicitly told not to write Markdown/LaTeX delimiters verbatim in XML mode.
- Examples cover inline and standalone formulas.
- Shell-safe relative
@file input is recommended for formula-heavy content.
- The repository's Skill format check passes.
Validation
I prepared the documentation-only change locally and verified it with:
node scripts/skill-format-check/index.js
✅ Skill format check passed!
git diff --check
✅ no whitespace errors
I can open a PR with the prepared patch once a fork branch is available.
Summary
Clarify the
lark-docSkill guidance for mathematical formulas so AI agents do not write Markdown/LaTeX delimiters as literal text when the document command is using the default XML format.Problem
lark-cli docs +createanddocs +updatedefault to--doc-format xml. The XML reference currently lists<latex>E = mc^2</latex>in the inline-component table, but the format-dependent rule is easy to miss.As a result, an agent may generate content such as:
In XML mode,
$...$,$$...$$,\(...\), and\[...\]are ordinary text. They can therefore appear verbatim in the Feishu/Lark document instead of becoming native formula nodes.The correct XML is:
Markdown writes are different:
$...$is valid only when the command explicitly uses--doc-format markdown.Proposed Change
Update the existing
lark-docSkill rather than adding a duplicate Skill:skills/lark-doc/SKILL.md.references/lark-doc-xml.mdcovering:$...$,$$...$$,\(...\), and\[...\]to<latex>...</latex>;&,<, and>inside formulas;<pre>/<code>for formulas;@fileinput for content containing$and backslashes.references/lark-doc-md.md.docs +fetch --doc-format xml --detail fullcheck to verify that the content contains<latex>nodes rather than literal delimiters.Acceptance Criteria
@fileinput is recommended for formula-heavy content.Validation
I prepared the documentation-only change locally and verified it with:
I can open a PR with the prepared patch once a fork branch is available.