docs: add approval skill command references - #1630
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR rewrites approval-skill routing to use per-command reference markdown files, adds new reference docs for approval lookup, instance operations, and task operations, and tightens initiation and write-operation guidance around dry-run, user confirmation, and parameter sourcing. ChangesApproval skill reference documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
skills/lark-approval/references/lark-approval-instance-initiated.md (1)
38-44: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueFix pipe character escaping in parameters table.
Same table formatting issue as
tasks-query.md: the\|escape syntax for literal pipes in cells (e.g.,zh-CN \| en-US \| ja-JP,user_id \| union_id \| open_id) is fragile across Markdown renderers. Use|or comma-separated values for reliability.🤖 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 `@skills/lark-approval/references/lark-approval-instance-initiated.md` around lines 38 - 44, The parameters table in the approval docs uses escaped pipe characters in cell text, which can break rendering in some Markdown parsers. Update the affected entries in the table to avoid literal `\|` usage by switching to safer separators such as `&`#124`;` or commas, especially for the `locale` and `user_id_type` values. Keep the table structure intact and ensure the rewritten text remains readable in the same documentation section.skills/lark-approval/references/lark-approval-tasks-query.md (1)
1-90: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueStandardize pipe character escaping across all tables.
Multiple tables in this file use
\|to represent literal pipes in cell content (e.g.,zh-CN \| en-US \| ja-JP). This escape syntax works in some Markdown renderers but fails in others, and it triggered markdownlint warnings. Replace all\|with|or rephrase to avoid pipes entirely for maximum compatibility.🤖 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 `@skills/lark-approval/references/lark-approval-tasks-query.md` around lines 1 - 90, Multiple tables in approval-tasks-query.md still use escaped pipe characters like \| in cell content, which is inconsistent and triggers markdownlint; update the table entries in the 参数 and相关 sections to avoid literal pipes by replacing them with &`#124`; or rephrasing the text. Use the table rows for locale, user_id_type, and --format as the main targets, and make the escaping style consistent throughout the document.
🤖 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-approval/references/lark-approval-tasks-query.md`:
- Around line 34-46: The parameters table in lark-approval-tasks-query.md has
malformed Markdown rows that will render incorrectly. Fix the table entries for
locale and page_token by replacing the escaped pipe separators with a safe
delimiter such as HTML entities or comma-separated values, and split the merged
--as user and --format rows into separate table rows so the table stays a
consistent 3-column layout.
---
Nitpick comments:
In `@skills/lark-approval/references/lark-approval-instance-initiated.md`:
- Around line 38-44: The parameters table in the approval docs uses escaped pipe
characters in cell text, which can break rendering in some Markdown parsers.
Update the affected entries in the table to avoid literal `\|` usage by
switching to safer separators such as `&`#124`;` or commas, especially for the
`locale` and `user_id_type` values. Keep the table structure intact and ensure
the rewritten text remains readable in the same documentation section.
In `@skills/lark-approval/references/lark-approval-tasks-query.md`:
- Around line 1-90: Multiple tables in approval-tasks-query.md still use escaped
pipe characters like \| in cell content, which is inconsistent and triggers
markdownlint; update the table entries in the 参数 and相关 sections to avoid literal
pipes by replacing them with &`#124`; or rephrasing the text. Use the table rows
for locale, user_id_type, and --format as the main targets, and make the
escaping style consistent throughout the document.
🪄 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: 6703a449-532c-43c4-be25-6e414520e18c
📒 Files selected for processing (12)
skills/lark-approval/SKILL.mdskills/lark-approval/references/lark-approval-instance-cancel.mdskills/lark-approval/references/lark-approval-instance-cc.mdskills/lark-approval/references/lark-approval-instance-get.mdskills/lark-approval/references/lark-approval-instance-initiated.mdskills/lark-approval/references/lark-approval-tasks-add-sign.mdskills/lark-approval/references/lark-approval-tasks-approve.mdskills/lark-approval/references/lark-approval-tasks-query.mdskills/lark-approval/references/lark-approval-tasks-reject.mdskills/lark-approval/references/lark-approval-tasks-remind.mdskills/lark-approval/references/lark-approval-tasks-rollback.mdskills/lark-approval/references/lark-approval-tasks-transfer.md
76563b5 to
c3fa3ff
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
skills/lark-approval/references/lark-approval-instances-cancel.md (1)
35-43: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winClarify that
instance_codeis a JSON body field, not a CLI flag.The parameter table mixes CLI flags (
--data,--as,--yes) with JSON body fields (instance_code) at the same level. Users may mistakenly try--instance_code <value>instead of nesting it inside--data. Consider restructuring to either:
- Explicitly label
instance_codeas "JSON body field" or indent it under--data, or- Consolidate into a single
--datarow that notes "must includeinstance_code".🤖 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 `@skills/lark-approval/references/lark-approval-instances-cancel.md` around lines 35 - 43, The parameter table mixes CLI flags with request-body fields, so update the `instance_code` entry in the `lark-approval instances cancel` docs to clearly indicate it belongs inside the JSON passed via `--data`, not as a standalone flag. Either relabel it as a JSON body field or nest it under the `--data` description so users do not infer a `--instance_code` option.skills/lark-approval/references/lark-approval-approvals-search.md (2)
103-105: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd brief explanation for the
--yesflag.The follow-up example includes
--yeswithout context. Consider adding a brief parenthetical, e.g., "(--yes用于确认执行写操作)", or reference the initiate workflow doc for details on when this flag is required.🤖 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 `@skills/lark-approval/references/lark-approval-approvals-search.md` around lines 103 - 105, The example command in the approvals search docs uses the `--yes` flag without explaining its purpose. Update the relevant CLI example in the approvals search reference to add a brief parenthetical explanation for `--yes`, or point readers to the initiate workflow doc; keep the note near the `lark-cli approval instances create` example so it is easy to understand why the flag is needed.
61-71: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueStandardize command reference notation in prose.
The document uses inconsistent notation to refer to the same command: line 61 uses
instances.create(dot notation), while line 69 usesapproval instances create(space-separated). Choose one style and apply it consistently throughout—preferably matching the actual CLI invocation format (lark-cli approval instances create) or a simplified consistent shorthand.🤖 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 `@skills/lark-approval/references/lark-approval-approvals-search.md` around lines 61 - 71, The references to the approval instance creation command are inconsistent in the prose, mixing dot notation and space-separated notation. Update the wording in the approvals search guide so the same command is described with one consistent style throughout, using the unique command references around approvals search, approvals get, and instances create to keep the flow aligned. Make sure every occurrence matches the chosen CLI reference format and avoid alternating between shorthand and invocation-like forms.
🤖 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-approval/references/lark-approval-initiate.md`:
- Around line 112-132: The terminology in the high-frequency control reference
is inconsistent: “自定义详情” is a typo in the radio/radioV2 guidance. Update the
wording in the lark-approval initiate reference section so it uses “定义详情” (or
“审批定义详情”) consistently with the rest of the document, specifically in the
radio/radioV2 bullet where option.value is described.
In `@skills/lark-approval/SKILL.md`:
- Around line 53-84: The API Resources section in SKILL.md conflicts with the
earlier workflow guidance by making schema inspection mandatory for native API
calls, which undermines the reference-first approach. Update the wording around
the approval.<resource>.<method> and approval <resource> <method> usage so
references remain the primary source, and make schema lookup optional or
explicitly limited to raw/advanced API usage; ensure the guidance is consistent
with the existing workflow text and the relevant API resource listings.
---
Nitpick comments:
In `@skills/lark-approval/references/lark-approval-approvals-search.md`:
- Around line 103-105: The example command in the approvals search docs uses the
`--yes` flag without explaining its purpose. Update the relevant CLI example in
the approvals search reference to add a brief parenthetical explanation for
`--yes`, or point readers to the initiate workflow doc; keep the note near the
`lark-cli approval instances create` example so it is easy to understand why the
flag is needed.
- Around line 61-71: The references to the approval instance creation command
are inconsistent in the prose, mixing dot notation and space-separated notation.
Update the wording in the approvals search guide so the same command is
described with one consistent style throughout, using the unique command
references around approvals search, approvals get, and instances create to keep
the flow aligned. Make sure every occurrence matches the chosen CLI reference
format and avoid alternating between shorthand and invocation-like forms.
In `@skills/lark-approval/references/lark-approval-instances-cancel.md`:
- Around line 35-43: The parameter table mixes CLI flags with request-body
fields, so update the `instance_code` entry in the `lark-approval instances
cancel` docs to clearly indicate it belongs inside the JSON passed via `--data`,
not as a standalone flag. Either relabel it as a JSON body field or nest it
under the `--data` description so users do not infer a `--instance_code` option.
🪄 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: 30310067-4e4e-405d-a7fd-41b717c0c412
📒 Files selected for processing (17)
skill-template/domains/approval.mdskills/lark-approval/SKILL.mdskills/lark-approval/references/lark-approval-approvals-get.mdskills/lark-approval/references/lark-approval-approvals-search.mdskills/lark-approval/references/lark-approval-initiate.mdskills/lark-approval/references/lark-approval-instance-value-sourcing.mdskills/lark-approval/references/lark-approval-instances-cancel.mdskills/lark-approval/references/lark-approval-instances-cc.mdskills/lark-approval/references/lark-approval-instances-get.mdskills/lark-approval/references/lark-approval-instances-initiated.mdskills/lark-approval/references/lark-approval-tasks-add-sign.mdskills/lark-approval/references/lark-approval-tasks-approve.mdskills/lark-approval/references/lark-approval-tasks-query.mdskills/lark-approval/references/lark-approval-tasks-reject.mdskills/lark-approval/references/lark-approval-tasks-remind.mdskills/lark-approval/references/lark-approval-tasks-rollback.mdskills/lark-approval/references/lark-approval-tasks-transfer.md
✅ Files skipped from review due to trivial changes (6)
- skills/lark-approval/references/lark-approval-instances-cc.md
- skills/lark-approval/references/lark-approval-tasks-approve.md
- skills/lark-approval/references/lark-approval-instances-get.md
- skills/lark-approval/references/lark-approval-instances-initiated.md
- skills/lark-approval/references/lark-approval-tasks-reject.md
- skills/lark-approval/references/lark-approval-tasks-add-sign.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/lark-approval/references/lark-approval-tasks-transfer.md
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 2
🧹 Nitpick comments (3)
skills/lark-approval/references/lark-approval-instances-cancel.md (1)
35-43: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winClarify that
instance_codeis a JSON body field, not a CLI flag.The parameter table mixes CLI flags (
--data,--as,--yes) with JSON body fields (instance_code) at the same level. Users may mistakenly try--instance_code <value>instead of nesting it inside--data. Consider restructuring to either:
- Explicitly label
instance_codeas "JSON body field" or indent it under--data, or- Consolidate into a single
--datarow that notes "must includeinstance_code".🤖 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 `@skills/lark-approval/references/lark-approval-instances-cancel.md` around lines 35 - 43, The parameter table mixes CLI flags with request-body fields, so update the `instance_code` entry in the `lark-approval instances cancel` docs to clearly indicate it belongs inside the JSON passed via `--data`, not as a standalone flag. Either relabel it as a JSON body field or nest it under the `--data` description so users do not infer a `--instance_code` option.skills/lark-approval/references/lark-approval-approvals-search.md (2)
103-105: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd brief explanation for the
--yesflag.The follow-up example includes
--yeswithout context. Consider adding a brief parenthetical, e.g., "(--yes用于确认执行写操作)", or reference the initiate workflow doc for details on when this flag is required.🤖 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 `@skills/lark-approval/references/lark-approval-approvals-search.md` around lines 103 - 105, The example command in the approvals search docs uses the `--yes` flag without explaining its purpose. Update the relevant CLI example in the approvals search reference to add a brief parenthetical explanation for `--yes`, or point readers to the initiate workflow doc; keep the note near the `lark-cli approval instances create` example so it is easy to understand why the flag is needed.
61-71: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueStandardize command reference notation in prose.
The document uses inconsistent notation to refer to the same command: line 61 uses
instances.create(dot notation), while line 69 usesapproval instances create(space-separated). Choose one style and apply it consistently throughout—preferably matching the actual CLI invocation format (lark-cli approval instances create) or a simplified consistent shorthand.🤖 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 `@skills/lark-approval/references/lark-approval-approvals-search.md` around lines 61 - 71, The references to the approval instance creation command are inconsistent in the prose, mixing dot notation and space-separated notation. Update the wording in the approvals search guide so the same command is described with one consistent style throughout, using the unique command references around approvals search, approvals get, and instances create to keep the flow aligned. Make sure every occurrence matches the chosen CLI reference format and avoid alternating between shorthand and invocation-like forms.
🤖 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-approval/references/lark-approval-initiate.md`:
- Around line 112-132: The terminology in the high-frequency control reference
is inconsistent: “自定义详情” is a typo in the radio/radioV2 guidance. Update the
wording in the lark-approval initiate reference section so it uses “定义详情” (or
“审批定义详情”) consistently with the rest of the document, specifically in the
radio/radioV2 bullet where option.value is described.
In `@skills/lark-approval/SKILL.md`:
- Around line 53-84: The API Resources section in SKILL.md conflicts with the
earlier workflow guidance by making schema inspection mandatory for native API
calls, which undermines the reference-first approach. Update the wording around
the approval.<resource>.<method> and approval <resource> <method> usage so
references remain the primary source, and make schema lookup optional or
explicitly limited to raw/advanced API usage; ensure the guidance is consistent
with the existing workflow text and the relevant API resource listings.
---
Nitpick comments:
In `@skills/lark-approval/references/lark-approval-approvals-search.md`:
- Around line 103-105: The example command in the approvals search docs uses the
`--yes` flag without explaining its purpose. Update the relevant CLI example in
the approvals search reference to add a brief parenthetical explanation for
`--yes`, or point readers to the initiate workflow doc; keep the note near the
`lark-cli approval instances create` example so it is easy to understand why the
flag is needed.
- Around line 61-71: The references to the approval instance creation command
are inconsistent in the prose, mixing dot notation and space-separated notation.
Update the wording in the approvals search guide so the same command is
described with one consistent style throughout, using the unique command
references around approvals search, approvals get, and instances create to keep
the flow aligned. Make sure every occurrence matches the chosen CLI reference
format and avoid alternating between shorthand and invocation-like forms.
In `@skills/lark-approval/references/lark-approval-instances-cancel.md`:
- Around line 35-43: The parameter table mixes CLI flags with request-body
fields, so update the `instance_code` entry in the `lark-approval instances
cancel` docs to clearly indicate it belongs inside the JSON passed via `--data`,
not as a standalone flag. Either relabel it as a JSON body field or nest it
under the `--data` description so users do not infer a `--instance_code` option.
🪄 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: 30310067-4e4e-405d-a7fd-41b717c0c412
📒 Files selected for processing (17)
skill-template/domains/approval.mdskills/lark-approval/SKILL.mdskills/lark-approval/references/lark-approval-approvals-get.mdskills/lark-approval/references/lark-approval-approvals-search.mdskills/lark-approval/references/lark-approval-initiate.mdskills/lark-approval/references/lark-approval-instance-value-sourcing.mdskills/lark-approval/references/lark-approval-instances-cancel.mdskills/lark-approval/references/lark-approval-instances-cc.mdskills/lark-approval/references/lark-approval-instances-get.mdskills/lark-approval/references/lark-approval-instances-initiated.mdskills/lark-approval/references/lark-approval-tasks-add-sign.mdskills/lark-approval/references/lark-approval-tasks-approve.mdskills/lark-approval/references/lark-approval-tasks-query.mdskills/lark-approval/references/lark-approval-tasks-reject.mdskills/lark-approval/references/lark-approval-tasks-remind.mdskills/lark-approval/references/lark-approval-tasks-rollback.mdskills/lark-approval/references/lark-approval-tasks-transfer.md
✅ Files skipped from review due to trivial changes (6)
- skills/lark-approval/references/lark-approval-instances-cc.md
- skills/lark-approval/references/lark-approval-tasks-approve.md
- skills/lark-approval/references/lark-approval-instances-get.md
- skills/lark-approval/references/lark-approval-instances-initiated.md
- skills/lark-approval/references/lark-approval-tasks-reject.md
- skills/lark-approval/references/lark-approval-tasks-add-sign.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/lark-approval/references/lark-approval-tasks-transfer.md
🛑 Comments failed to post (2)
skills/lark-approval/references/lark-approval-initiate.md (1)
112-132: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Typo: "自定义详情" should be "定义详情".
Line 119 says "取自定义详情里的 option.value" — "自定义" (custom) appears to be a typo for "定义" (definition). It should read "取定义详情里的 option.value" or "取审批定义详情里的 option.value" to match the document's terminology elsewhere.
🤖 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 `@skills/lark-approval/references/lark-approval-initiate.md` around lines 112 - 132, The terminology in the high-frequency control reference is inconsistent: “自定义详情” is a typo in the radio/radioV2 guidance. Update the wording in the lark-approval initiate reference section so it uses “定义详情” (or “审批定义详情”) consistently with the rest of the document, specifically in the radio/radioV2 bullet where option.value is described.skills/lark-approval/SKILL.md (1)
53-84: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Contradictory guidance: reference-first vs. schema-required.
Line 15 tells users to "read references first, don't guess fields," but Line 60 newly adds a mandatory
schemainspection requirement for native APIs. This undermines the PR's stated goal of shifting from schema inspection to reference files. Either remove the schema mandate, soften it to "references are primary; use schema only if references are insufficient," or clarify that the API Resources section is for advanced/raw usage while the workflow section above is the standard path.🤖 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 `@skills/lark-approval/SKILL.md` around lines 53 - 84, The API Resources section in SKILL.md conflicts with the earlier workflow guidance by making schema inspection mandatory for native API calls, which undermines the reference-first approach. Update the wording around the approval.<resource>.<method> and approval <resource> <method> usage so references remain the primary source, and make schema lookup optional or explicitly limited to raw/advanced API usage; ensure the guidance is consistent with the existing workflow text and the relevant API resource listings.
085990d to
7744541
Compare
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@137f118d7f75c78aeca8bf3c1a6bff8d3b9240f3🧩 Skill updatenpx skills add Paulazaaza-dev/cli#feat/approval-optimize-skill -y -g |
7744541 to
04ca8fe
Compare
04ca8fe to
dd9186e
Compare
0a6964c to
87007e5
Compare
87007e5 to
137f118
Compare
Summary
Add detailed command-to-reference mapping for the approval skill so agents can jump to the exact reference file for each
lark-cli approvalcommand.Changes
skills/lark-approval/SKILL.mdTest Plan
Related Issues
Summary by CodeRabbit
New Features
Documentation