feat: add skills command to read embedded skill content

[liangshuo-1]

Summary

Re-homes #1277 into the upstream repo (it originated from a fork) and cherry-picks it onto the current main. Original feature by @dc-bytedance — the two original commits are preserved; a follow-up commit applies the review feedback.

Adds a lark-cli skills command group that reads skill content compiled into the binary at build time via go:embed, giving AI agents a version-consistent source — and a fallback for when on-disk skills are missing or stale. It does not replace or thin the on-disk skills.

Changes

• skills_embed.go (package main): //go:embed of each skill's SKILL.md + references/ (plus lark-whiteboard's routes//scenes/), excluding machine-resource dirs (assets/, scripts/). An init() injects the tree via cmd.SetEmbeddedSkillContent, keeping main.go self-contained so the single-file preview build still compiles.
• internal/skillcontent/reader.go: pure logic over an injected fs.FS — List, ListPath (one-layer, ls-style), ReadSkill, ReadReference, with a shared path-traversal guard.
• cmd/skill/skill.go: the skills group — list (catalog, or one-layer listing of <name>/<name>/<sub>) and read (<name>, <name> <path>, or <name>/<path>). Typed errors (validation → exit 2, file_io → exit 5); raw stdout stays byte-identical to the file, guidance goes to stderr.
• Registered in cmd/build.go; Factory.SkillContent field added.
• Unit tests for both packages.

Follow-up commit (review fixes)

• Fix stale comments referencing the renamed cmd.WithSkillContent → SetEmbeddedSkillContent (Execute takes no options; the override path is the package-level setter).
• Unify the binary-size figures — keep only the ~3.3 MB saved delta (absolute size depends on build/ldflags).
• Scope the skills help text to agent-readable content (assets//scripts/ are not embedded, so "stays in sync" is not unconditional).
• Trim comment density to the house style.

Test Plan

• go build ./... (rc=0 on current main)
• go test ./internal/skillcontent/... ./cmd/skill/...
• gofmt clean
• Manual: skills list, skills read <skill>, read <skill> <path>; error paths (read no-such-skill, traversal ../../etc/passwd) exit 2 with empty stdout

Supersedes #1277.

Summary by CodeRabbit

Release Notes

• New Features

  • Added skills command group with two subcommands:
    • skills list — view available skills and directory contents with JSON output support
    • skills read — retrieve skill documentation and reference files in raw or JSON format

• Tests

  • Added comprehensive test suite covering skill commands, path validation, and error scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2ec423d6-3863-4f70-b753-5040388bd602

📥 Commits

Reviewing files that changed from the base of the PR and between e40ef66 and 6ba9912.

📒 Files selected for processing (7)

• cmd/build.go
• cmd/skill/skill.go
• cmd/skill/skill_test.go
• internal/cmdutil/factory.go
• internal/skillcontent/reader.go
• internal/skillcontent/reader_test.go
• skills_embed.go

---

📝 Walkthrough

Walkthrough

This PR adds a complete embedded skills system to the CLI: a reader library that enumerates and serves skill content with YAML frontmatter parsing, CLI commands to list and read skills with JSON and raw output modes, and compile-time embedding wiring that bundles skill files into the binary.

Changes

Embedded Skills Content and CLI Commands

Layer / File(s)	Summary
Skill content reader library and types internal/skillcontent/reader.go, internal/skillcontent/reader_test.go	Reader scans embedded directories for skills (identified by SKILL.md), extracts YAML frontmatter metadata, and provides listing and reading operations with path sanitization and traversal rejection. Comprehensive tests validate listing, path-scoped queries, frontmatter parsing, and error cases.
Skills CLI commands cmd/skill/skill.go, cmd/skill/skill_test.go	skills list and skills read subcommands serve skill content as JSON envelopes or raw file bytes; read includes contextual guidance for SKILL.md that routes to stderr and handles cross-skill reference rewriting. Tests cover both commands' success and error paths including catalog filtering and nil-content detection.
Build and embedding integration cmd/build.go, internal/cmdutil/factory.go, skills_embed.go	Factory struct gains SkillContent fs.FS field; build wires embedded skills into factory and registers skill command; skills_embed.go uses go:embed to bundle skill files at compile time and registers them during init.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as User CLI
    participant Cmd as Skill Command
    participant Reader as skillcontent.Reader
    participant Output as stdout/stderr
    CLI->>Cmd: skills list [name[/path]]
    Cmd->>Reader: List() or ListPath()
    Reader-->>Cmd: SkillInfo[] or DirEntry[]
    Cmd->>Output: JSON envelope
    CLI->>Cmd: skills read <name>[/<path>]
    Cmd->>Reader: ReadSkill() or ReadReference()
    Reader-->>Cmd: []byte content
    Cmd->>Output: Raw bytes or JSON envelope + guidance

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

feature, size/XL

Suggested reviewers

• GeekyMax

Poem

🐰 Embedded skills bloom in binary light,
Reader and command dance in perfect flight,
YAML parsed, paths secured with care,
Agent wisdom everywhere!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a skills command to read embedded skill content from the binary.
Description check	✅ Passed	The description covers all required template sections with detailed information about the feature, changes, test plan, and context; however, 'Related Issues' section shows 'None' instead of being populated with issue references.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/skill-content-read

---

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

[codecov]

Codecov Report

❌ Patch coverage is 89.42731% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.20%. Comparing base (e40ef66) to head (6ba9912).

Files with missing lines	Patch %	Lines
internal/skillcontent/reader.go	87.71%	8 Missing and 6 partials ⚠️
cmd/skill/skill.go	94.23%	3 Missing and 3 partials ⚠️
skills_embed.go	50.00%	2 Missing and 1 partial ⚠️
cmd/build.go	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1318      +/-   ##
==========================================
+ Coverage   71.14%   71.20%   +0.06%     
==========================================
  Files         685      688       +3     
  Lines       65770    65997     +227     
==========================================
+ Hits        46793    46996     +203     
- Misses      15326    15340      +14     
- Partials     3651     3661      +10     

☔ 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@6ba9912bd215dba55e2c683f0ed48c089b0cdc64

🧩 Skill update

npx skills add larksuite/cli#feat/skill-content-read -y -g