Reduce duplicated context in bundled Lark Skills by relying on CLI schemas and risk gates

[elenafly-eng]

Reduce duplicated context in bundled Lark Skills by relying on CLI schemas and risk gates

Summary

Bundled Lark Skills currently repeat substantial command and parameter guidance that is already available through lark-cli help/schema metadata. Several always-loaded Skill descriptions are also long enough to include implementation detail rather than only routing boundaries.

The shared write policy additionally asks for confirmation before every write or delete, even when the user has explicitly requested a routine, reversible write. This duplicates the CLI's exit-code-10 high-risk gate and the stricter confirmation rules already defined by individual Skills for sending, deletion, bulk mutation, permission changes, and ownership transfer.

This makes the Skill context larger and more rigid than necessary, while creating multiple places that must stay synchronized as commands evolve.

User-visible impact

• More always-loaded prompt context is consumed before a Lark Skill is selected.
• Command documentation can drift between SKILL.md and the actual CLI schema/help.
• Routine explicit requests can cause redundant confirmation turns.
• Risk rules are harder to audit because the same behavior is described at several layers.

Evidence

On one current installation:

• 27 bundled Lark Skills contain about 4,252 lines / 348 KB of SKILL.md content.
• The always-loaded metadata descriptions for all exposed Skills totaled 21,325 bytes.
• Replacing only six long Lark descriptions (lark-apps, lark-drive, lark-sheets, lark-doc, lark-slides, and lark-wiki) with routing-focused descriptions reduced that total to 19,987 bytes: 1,338 bytes, or about 6.3%, without changing the Skill bodies or CLI behavior.
• Several Skills already declare CLI help/schema metadata while also maintaining handwritten command/parameter tables in prose.
• lark-apps described ordinary landing pages/dashboards as HTML-app signals inside the body while its routing description excluded ordinary websites; its local/cloud decision table also contained conflicting defaults.
• lark-apps allowed a generic “do it without asking” instruction to pre-authorize publishing, conflicting with the higher-level external-release gate.
• lark-doc instructed an unscoped auth login, while lark-shared requires every login to specify --domain or --scope.

These figures are illustrative rather than a proposed size limit.

Root cause

The same contract is maintained in several places:

1. Always-loaded Skill descriptions.
2. Handwritten command and parameter guidance in SKILL.md.
3. CLI help/schema metadata.
4. A shared blanket confirmation rule.
5. Per-Skill confirmation rules and the CLI exit-code-10 risk gate.

Because these layers are edited independently, updates can increase context size or leave stale instructions behind.

Proposed change

1. Keep Skill descriptions routing-focused

Descriptions should state:

• the domain and primary intents that trigger the Skill;
• the most important negative boundaries or handoffs;
• identifiers that make routing unambiguous when relevant.

Move command syntax, capability inventories, and workflow detail out of always-loaded descriptions.

2. Treat CLI schema/help as the command interface

• Generate or progressively load command and parameter guidance from the registered CLI schema/help.
• Avoid manually duplicating exhaustive command tables in SKILL.md when the tool can expose the same contract.
• Keep prose only for domain judgment, multi-step workflow choices, safety boundaries, and behavior not expressible in the schema.
• Add a consistency check so referenced commands and parameters must exist in the installed CLI version.

3. Make confirmation risk-based

An explicit current-turn request to perform a routine, reversible write should count as authorization for that write. Ask again when the target, scope, identity, or content is ambiguous.

Continue to require confirmation for genuinely higher-risk actions, including:

• deletion;
• bulk mutation;
• public permission changes;
• owner transfer;
• external sending where the business Skill requires a preview/confirmation;
• any action classified by the CLI's exit-code-10 risk gate.

4. Validate cross-Skill contracts

• Ensure business Skills do not weaken shared authentication or risk rules.
• Check positive and negative routing examples for contradictions between frontmatter and the body.
• Treat external publishing as a separate confirmation boundary even when intermediate routine steps are pre-authorized.

Call chain / affected components

• Bundled Lark Skill packaging and update pipeline.
• Skill frontmatter descriptions consumed by the agent's routing catalog.
• SKILL.md command references and parameter tables.
• CLI command registry, help/schema generation, and any cliHelp metadata.
• Shared write policy and per-Skill risk/confirmation instructions.
• Integrity/doctor checks that validate installed Skill references against the CLI.

Exact source paths and generator entry points are to be confirmed by maintainers.

Scope boundaries

In scope:

• context and interface deduplication;
• routing-focused descriptions;
• schema-derived command guidance;
• explicit separation of routine authorization from high-risk confirmation;
• automated consistency checks.

Out of scope:

• changing Lark OpenAPI behavior;
• renaming or removing public CLI commands without a separate compatibility plan;
• weakening delete, bulk-edit, permission, ownership-transfer, or send safeguards;
• bypassing the exit-code-10 confirmation protocol.

Compatibility and migration

• Existing CLI commands and flags should remain compatible.
• If command tables are generated rather than handwritten, generation must be versioned with the installed CLI schema.
• Local overlays should fail closed when the upstream Skill version or expected source text changes; they must not silently overwrite a newer official policy.

Acceptance criteria

Happy paths

1. Routing prompts for Apps, Drive, Sheets, Docs, Slides, and Wiki select the same intended Skill after descriptions are shortened.
2. An explicit request such as “add one row to this sheet” proceeds without an extra generic confirmation when the target and content are clear.
3. Command guidance loaded for a Skill matches the installed CLI schema and contains no unknown command or parameter references.
4. Business-Skill authentication guidance always specifies a domain or concrete scope and matches the shared authentication contract.

Edge and boundary cases

1. “Organize my Drive” asks for target/scope clarification rather than guessing a broad mutation.
2. Delete, bulk-update, public-permission, owner-transfer, and Skill-defined send actions retain their confirmation requirements.
3. An exit-code-10 response always stops execution, displays the risk information, and requires explicit confirmation before retrying with the required flag.
4. A CLI schema/version change that invalidates generated guidance fails the integrity check instead of silently retaining stale instructions.

Non-goals / follow-up

This issue is separate from installation completeness problems where lark-cli update reports success but bundled Skill files contain unresolved local references. The two checks may eventually share a single Skill integrity/doctor command, but they have different root causes and acceptance criteria.