Skip to content

Document installing the skills with lk skills #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bcherry merged 3 commits into from
Oct 9, 2026
Merged

Document installing the skills with lk skills #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
29fbc3e
Document installing the skills with lk skills
claude Sep 24, 2026
119674e
Describe lk skills install as v2.19.0 behaves
claude Oct 9, 2026
56759da
Trim distribution details from AGENTS.md and the README
claude Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 14 additions & 32 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,9 @@ LiveKit Inference. When the user runs the LiveKit server themselves, call it Liv
opposed to LiveKit Cloud. Using "self-hosted" for both leads agents to wrongly rule out Cloud
features for anyone who hosts their own agent.

**No version numbers in frontmatter.** Every install path tracks a skill by its content: the
plugin by commit, the docs index by SHA-256 digest, `npx skills` by the hash in its lock file.
A hand-maintained `metadata.version` never got bumped and showed the same number for different
content, so `validate.py` rejects it.
**No version numbers in frontmatter or `plugin.json`.** Every install path tracks a skill by its
content, so a merged change ships without a bump. A hand-maintained `metadata.version` never got
bumped and showed the same number for different content, so `validate.py` rejects it.

**Explain why.** Capable models read these skills, and they respond better to a reason than to a
bare command. "Restart after every edit — a running session holds the old code" works better than
Expand Down Expand Up @@ -219,40 +218,23 @@ Delete the directory. To rename, create the new directory and delete the old one
stub behind: a stub's description is loaded into every user's context on every request, forever,
to say "don't use me" — the opposite of what the set is trying to do for context.

Skills are installed from this repository — `npx skills add livekit/agent-skills` today, and the
LiveKit CLI. Installers take `skills/<name>/SKILL.md` plus that skill's `references/`, so keep that
layout stable: a renamed directory is a removed skill and a new one, and nothing here can reach a
user's existing local copy. The README tells users of a removed skill to reinstall.
Skills are installed from this repository, with the LiveKit CLI (`lk skills`) or
`npx skills add livekit/agent-skills`. Installers take `skills/<name>/SKILL.md` plus that skill's
`references/`, so keep that layout stable: a renamed directory is a removed skill and a new one,
and nothing here can reach a user's existing local copy. The README tells users of a removed skill to reinstall.

Removing a skill here also removes it from the well-known index on the docs site at its next
rebuild, and Claude Code plugin users lose it the next time their marketplace updates.

## Distribution

The same `skills/` directory reaches users through three channels. None of them need a manual
release step, so a merged change to `skills/**` is a shipped change.

- **Claude Code plugin.** `.claude-plugin/marketplace.json` makes this repo a marketplace named
`livekit` with one plugin, also named `livekit`, sourced from the repo root. `plugin.json` bundles
the Docs MCP server; the skills are picked up from `skills/` automatically. `plugin.json` has no
`version` on purpose: without one, Claude Code treats each commit as a new version, so users get
a change as soon as their marketplace updates. Adding a `version` means every skill change also
needs a bump, or users stay on the old copy. Third-party marketplaces don't auto-update by
default; the README tells users how to turn it on. Check manifest edits with `claude plugin validate .`.
- **`npx skills add livekit/agent-skills`**, which reads `skills/` from GitHub directly.
- **The well-known index** at `https://docs.livekit.io/.well-known/agent-skills/index.json` (and
the older `/.well-known/skills/` path), with a SHA-256 digest per skill. The docs site generates
it from this repo. A push to `skills/**` on `main` runs `notify-skill-changes.yml`, which
dispatches `agent-skills-updated` to `livekit/internal-actions`; that forwards it to
`livekit/web`, which regenerates the index and opens a PR.

Plugin skills are namespaced (`/livekit:building-livekit-agents`). Skill names still matter for
the other channels, and for anyone invoking a skill by hand, so the naming rules above apply
unchanged.

For a listing in a marketplace we don't control, such as Anthropic's `claude-plugins-official`,
the entry should point at this repo with a GitHub source pinned to a full commit `sha` rather than
a branch, and be bumped deliberately.
A merged change to `skills/**` ships to every channel with no release step:

- **Claude Code plugin:** `.claude-plugin/` makes this repo the `livekit` marketplace and plugin.
- **LiveKit CLI:** `lk skills install` installs from this repository.
- **`npx skills`:** `npx skills add livekit/agent-skills` reads `skills/` from GitHub.
- **Docs site index:** `livekit/web` regenerates `docs.livekit.io/.well-known/agent-skills/` when
`notify-skill-changes.yml` reports a change.

## Things not to do here

Expand Down
18 changes: 14 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,21 @@ You don't invoke skills by name. Your coding agent picks them up from what you s

## Install

### LiveKit CLI

```bash
lk skills install
```

That installs all seven skills for the coding agents you pick, with the ones it detects
preselected, and adds the LiveKit Docs MCP server to each one that supports it. `lk skills update` pulls the latest; `lk skills --help` has
the rest. `lk agent init` offers to do this for new agent projects.

### Claude Code

Install the LiveKit plugin. It bundles all seven skills and the LiveKit Docs MCP server.

Pick one: the plugin or `npx skills add`, not both. Claude Code doesn't deduplicate plugin
Pick one: the plugin or `lk skills install`, not both. Claude Code doesn't deduplicate plugin
skills against project skills, so with both installed every description loads twice and the copies
compete with each other for routing.

Expand Down Expand Up @@ -73,9 +83,9 @@ You can also copy the folders you want from `skills/` into your agent's skills d
`lk agent simulate`, and the `lk agent` deploy commands. Install or update it from the [CLI docs](https://docs.livekit.io/intro/basics/cli).
The skills check for the commands they need and will tell you to update if one is missing.
- **A LiveKit Cloud project**, with `lk` authenticated to it, for simulations and deployment.
- **The LiveKit Docs MCP server** (optional, and already included in the Claude Code plugin). It's
the same source `lk docs` uses, with less friction. Setup for each coding agent is at
[docs.livekit.io/intro/mcp-server](https://docs.livekit.io/intro/mcp-server/).
- **The LiveKit Docs MCP server** (optional, and already set up by `lk skills install` and the
Claude Code plugin). It's the same source `lk docs` uses, with less friction. Setup for each
coding agent is at [docs.livekit.io/intro/mcp-server](https://docs.livekit.io/intro/mcp-server/).

## How the skills are built

Expand Down
Loading