feat: lk skills, installs LiveKit's agent skills and Docs MCP server

[bcherry]

Adds lk skills install|list|update|remove, which installs the skills from livekit/agent-skills into coding agents and adds the LiveKit Docs MCP server to their configs. Also: lk agent init offers to install skills into new agent projects, replacing the copies the starters used to commit.

lk skills install              # all skills + Docs MCP, for detected agents
lk skills install -a claude-code -a codex --global
lk skills list                 # installed / current / outdated / modified / untracked, plus MCP status
lk skills update               # latest skills, including renamed and new ones
lk skills remove

How it works

• Source: the tip of livekit/agent-skills main, fetched as a tarball from codeload. No git or Node needed. A hidden --ref flag installs from a branch, for trying skill PRs before they merge.
• Agents: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, Amp, Cline and Goose. They're detected from their config folders or their binaries on PATH; --agent overrides that, and interactive runs pick from a multi-select with detected agents preselected. Skill paths follow the npx skills table.
• Files: skills are copied, never symlinked (symlinks break on Windows). Agents that read .agents/skills share one copy; Claude Code, Windsurf and Goose get their own.
• Lock files: writes the same skills-lock.json (project) and ~/.agents/.skill-lock.json (global) that npx skills and gh skill use. Hashes are byte-identical to what npx skills computes, and the tree hash matches GitHub's folder SHA, so the three tools can manage each other's installs.
• Safety:
  • Skills you've edited are left alone unless you pass --force.
  • LiveKit skills with no lock entry, such as copies committed to the old starters, are "untracked" and replaced after a confirmation (automatically without a terminal, or with -y).
  • Skills LiveKit stops publishing are removed.
  • Archive entries that are symlinks, or that would escape the skill folder, are ignored.
• Docs MCP: added to each agent's project or user config. JSON/JSONC and TOML are edited in place, keeping existing formatting and comments. An existing livekit-docs entry is never replaced. For user-scope Claude Code it uses claude mcp add when claude is on PATH. Amp, Cline and Goose get manual setup instructions.
• Scaffolding: lk agent init shows the agent picker (detected agents preselected, none to skip) to install skills into the new project. Without a terminal it installs for detected agents; --skills=false skips. lk app create is unchanged.

New dependency: github.com/tailscale/hujson, for editing JSON/JSONC without reformatting.

Testing

• Unit tests in pkg/skills for archive parsing, hashing against vectors generated with Node's localeCompare and git write-tree, lock round-trips, install states, and MCP config edits. Command-level tests in cmd/lk/skills_test.go.
• Checked manually with a scratch $HOME:
  • lk skills install over an existing npx skills install left skills-lock.json unchanged.
  • Global install; Codex TOML; the ~/.claude.json fallback when claude isn't on PATH.
  • A clone of today's agent-starter-python: update --ref bcherry/skills-refresh swapped the untracked livekit-agents copies for the new skills.
• Not tested: the interactive prompts (they need a TTY), and Windows.

Related

• The starter repos are dropping their committed skills in separate PRs.
• The committed copies came from livekit/internal-actions/.github/workflows/sync.yml. It still lists both starters (and livekit/cloud-api-server) and a hardcoded SKILLS=(livekit-agents livekit-simulations), which needs updating for the Replace the two skills with seven smaller ones, add evals, and drop the downstream sync agent-skills#10 renames.

[u9g]

Demo of lk skills built from this branch (7882cca), run in a scratch project: list on an empty project, install with the interactive agent picker, list showing skills and Docs MCP status, the MCP entries written to .mcp.json and .codex/config.toml, update leaving a hand-edited skill alone, and remove with its confirmation.

lk-skills.mp4

[u9g]

lk skills remove deletes edited skills without saying so. You can see this in the demo, and it's in the code (skills.go#L808-L880). update protects edited skills, but remove lists them in its confirmation like every other folder.

[bcherry]

@u9g great catch, fixed