docs(okr): optimize okr skill

[syh-cpdsss]

Summary

Optimize the OKR skill documentation to improve clarity, add practical examples, and clarify scope boundaries. This update helps AI agents better understand when and how to use the OKR skill, and avoids confusion with related domains.

Changes

• Updated skill description to explicitly list out-of-scope responsibilities (task management, calendar, performance evaluation)
• Added identity context clarifying --as user default vs --as bot usage
• Removed redundant API usage instructions (schema/command pattern) and the permissions table
• Clarified cycles.objectives_position and objectives.key_results_position behavior — all IDs must be provided, order determines positioning
• Added a concrete command example for cycles.objectives_weight
• Added an "out of scope" section with cross-references to lark-task, lark-calendar, and lark-openapi-explorer

Test Plan

• Automated Evaluation passed

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Clarified OKR operation identity handling with --as user and --as bot options.
  • Expanded API resource constraint documentation for cycles and objectives, including explicit command examples.
  • Added section listing excluded skill domains for better scope clarity.
  • Removed redundant API resources section.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates the OKR skill documentation in skills/lark-okr/SKILL.md. Changes clarify how OKR operations are invoked (user vs. bot identity), expand API constraint documentation for objective and key result positioning with explicit ordering requirements, and define excluded feature boundaries. The raw API usage snippet is removed in favor of focused endpoint documentation.

Changes

OKR Skill Documentation Update

Layer / File(s)	Summary
Skill overview and operation identity skills/lark-okr/SKILL.md	Skill description rewording and new "身份" section documenting default operation identity (--as user) and alternate bot mode requiring appropriate permissions.
API resource constraints for positioning and weighting skills/lark-okr/SKILL.md	Enhanced validation guidance for cycles.objectives_position, cycles.objectives_weight, and objectives.key_results_position to require complete ID lists and clarify reordering by input sequence; added weight submission example.
Scope boundaries and documentation housekeeping skills/lark-okr/SKILL.md	Shortcuts table adjustment, removal of raw API invocation note, addition of "不在本 skill 范围" section listing excluded domains (tasks, calendar, performance evaluation), and removal of the permissions table.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• larksuite/cli#546: Extends the same OKR skill documentation with validation requirements and example input ordering for cycles.objectives_position / cycles.objectives_weight and objectives.key_results_position endpoints.

Suggested labels

domain/ccm, size/M

Suggested reviewers

• zhangzq0
• wittam-01

Poem

🐰 A skill so clear, its boundaries drawn,
Identities defined from dusk to dawn,
APIs ordered, constraints laid bare—
Scope lines marked with rabbit's care!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(okr): optimize okr skill' is concise and directly describes the main change—documentation optimization for the OKR skill.
Description check	✅ Passed	The description covers all required template sections: Summary, Changes, Test Plan, and Related Issues. All sections are completed with substantive content.
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 fix/okr-skill-optimization

---

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

[coderabbitai]

🧹 Nitpick comments (1)

skills/lark-okr/SKILL.md (1)

87-87: ⚡ Quick win

Consider using the full resource path in the cross-reference.

The reference says "objectives_weight" but earlier in the document (line 54) the full resource path is "cycles.objectives_weight". For clarity and precision, consider updating to:

-    - 类似 `objectives_weight`, 请求中必须同时修改对应目标下全部关键结果的权重,且所有权重值的和必须等于 1 ,否则会参数校验失败。
+    - 类似 `cycles.objectives_weight`, 请求中必须同时修改对应目标下全部关键结果的权重,且所有权重值的和必须等于 1 ,否则会参数校验失败。

This makes the cross-reference unambiguous and helps readers locate the referenced constraint.

🤖 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-okr/SKILL.md` at line 87, Update the ambiguous cross-reference
from `objectives_weight` to the full resource path `cycles.objectives_weight` in
the sentence mentioning the weight validation so readers can unambiguously
locate the field; edit the occurrence in SKILL.md (the line that currently reads
"类似 `objectives_weight`...") to use `cycles.objectives_weight` and ensure any
surrounding explanation still reads correctly with the fully qualified name.

🤖 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 `@skills/lark-okr/SKILL.md`:
- Line 87: Update the ambiguous cross-reference from `objectives_weight` to the
full resource path `cycles.objectives_weight` in the sentence mentioning the
weight validation so readers can unambiguously locate the field; edit the
occurrence in SKILL.md (the line that currently reads "类似
`objectives_weight`...") to use `cycles.objectives_weight` and ensure any
surrounding explanation still reads correctly with the fully qualified name.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5c6e2ed0-a949-42b0-873c-4ea7403a6fdd

📥 Commits

Reviewing files that changed from the base of the PR and between 7fdf558 and 83d543b.

📒 Files selected for processing (1)

• skills/lark-okr/SKILL.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.90%. Comparing base (7fdf558) to head (83d543b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1368   +/-   ##
=======================================
  Coverage   71.90%   71.90%           
=======================================
  Files         691      691           
  Lines       65629    65629           
=======================================
  Hits        47191    47191           
  Misses      14791    14791           
  Partials     3647     3647           

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#fix/okr-skill-optimization -y -g