CLI needs first-class in-product docs; skills should be optional enhancement, not required path

[timzhong1024]

Summary

The core issue is not just that a specific formula guide was hard to find. The larger problem is that lark-cli itself does not provide enough first-class, in-product documentation at the point of use.

Skills are useful, but they should be an enhancement layer, not the only practical way to access critical usage guidance.

What happened

While using guarded features such as formula/lookup-related Base operations, the CLI required reading a guide first and referenced a path like:

• skills/lark-base/references/formula-field-guide.md

That flow assumes the relevant skills/docs are already installed and locally accessible.

In practice, a user may have:

• installed @larksuite/cli
• successfully configured auth
• started using commands directly
• but not installed the separate skills package / skill set yet

In that situation, the CLI still works, but critical guidance becomes hard to access.

Problem statement

lark-cli currently relies too much on the skills ecosystem for documentation discoverability.

That creates an undesirable split:

• CLI binary: executable features
• Skills: practical documentation required to use some features correctly

From a user perspective, this means the base CLI experience can become under-documented unless they also know they should install skills.

Why this is a UX problem

Skills should be:

• optional productivity boost
• richer workflows
• reusable domain knowledge

But they should not be the only realistic path to understanding core command behavior or critical syntax rules.

For example, if a command blocks on formula safety and tells the user to read a guide first, then the CLI itself should be able to surface that guide in a directly accessible form, even if no extra skills are installed.

Desired principle

The CLI should provide a baseline documentation experience by itself.

Skills can still add:

• better workflows
• deeper examples
• scene-specific playbooks
• cross-tool orchestration

But core task-critical docs should remain accessible from the CLI product surface.

Suggestions

• Add built-in doc access such as:
  • lark-cli docs <topic>
  • lark-cli help <feature>
  • lark-cli guide formula
• When a command requires a guide first, print either:
  • inline concise guidance, or
  • a direct online URL, or
  • a built-in doc command the user can run immediately
• Make it explicit in onboarding that skills are optional but recommended
• Avoid error messages that assume a local skills/... path exists unless the CLI can verify it actually exists

What should remain true

The conclusion is unchanged:

• users need a clear documentation path at the moment they get blocked
• that path should come from the CLI product itself
• skills are valuable, but they should be additive, not mandatory for basic usability

Real-world context

This came up during real use of Base formula fields and whiteboard flows. The issue was not just one missing file, but that the CLI product surface did not provide enough self-contained documentation unless the separate skills layer was also installed.