From 29fbc3e4f56599e22974a37f75af4925a6e9e0ec Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 22:58:37 +0000 Subject: [PATCH 1/3] Document installing the skills with lk skills Adds the LiveKit CLI install path to the README and lists lk skills as a distribution channel in AGENTS.md. Merge once lk skills ships in a LiveKit CLI release. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GhopX4p6rY3MNkNQ1M832x --- AGENTS.md | 9 +++++---- README.md | 13 ++++++++++++- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ca176cf..3fcc639 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,9 +108,9 @@ opposed to LiveKit Cloud. Using "self-hosted" for both leads agents to wrongly r 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. +plugin by commit, the docs index by SHA-256 digest, `lk skills` and `npx skills` by the hash in +their lock file. 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 @@ -229,7 +229,7 @@ rebuild, and Claude Code plugin users lose it the next time their marketplace up ## Distribution -The same `skills/` directory reaches users through three channels. None of them need a manual +The same `skills/` directory reaches users through four 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 @@ -239,6 +239,7 @@ release step, so a merged change to `skills/**` is a shipped change. 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 .`. +- **The LiveKit CLI** (`lk skills`), which installs from this repository. - **`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 diff --git a/README.md b/README.md index 013f224..9a6db6f 100644 --- a/README.md +++ b/README.md @@ -37,11 +37,22 @@ 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 on your machine (Claude Code, Codex, Cursor, +GitHub Copilot, Gemini CLI, and others), and adds the LiveKit Docs MCP server to each one's +config. `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. From 119674e2e02357ccf3d200428e96cb1c13616a24 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 9 Oct 2026 19:09:31 +0000 Subject: [PATCH 2/3] Describe lk skills install as v2.19.0 behaves It installs for the agents you pick, with detected ones preselected, and adds the Docs MCP server only where the agent supports it. Note that it sets up the MCP server, and drop time-relative wording from AGENTS.md. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GhopX4p6rY3MNkNQ1M832x --- AGENTS.md | 8 ++++---- README.md | 14 +++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3fcc639..eb1be0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -219,10 +219,10 @@ 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//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//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. diff --git a/README.md b/README.md index 9a6db6f..3258337 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,10 @@ You don't invoke skills by name. Your coding agent picks them up from what you s lk skills install ``` -That installs all seven skills for the coding agents on your machine (Claude Code, Codex, Cursor, -GitHub Copilot, Gemini CLI, and others), and adds the LiveKit Docs MCP server to each one's -config. `lk skills update` pulls the latest; `lk skills --help` has the rest. -`lk agent init` offers to do this for new agent projects. +That installs all seven skills for the coding agents you pick (Claude Code, Codex, Cursor, GitHub +Copilot, Gemini CLI, and others; the ones it detects are 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 @@ -84,9 +84,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 From 56759dab4fdaabd3bf9f2ec16dec5b35f47bdb1f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 9 Oct 2026 19:10:13 +0000 Subject: [PATCH 3/3] Trim distribution details from AGENTS.md and the README Each channel is one line, the no-version rule no longer lists how each channel tracks content, and the README doesn't list supported agents. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GhopX4p6rY3MNkNQ1M832x --- AGENTS.md | 39 ++++++++++----------------------------- README.md | 5 ++--- 2 files changed, 12 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eb1be0d..b643c47 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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, `lk skills` and `npx skills` by the hash in -their 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 @@ -229,31 +228,13 @@ rebuild, and Claude Code plugin users lose it the next time their marketplace up ## Distribution -The same `skills/` directory reaches users through four 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 .`. -- **The LiveKit CLI** (`lk skills`), which installs from this repository. -- **`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 diff --git a/README.md b/README.md index 3258337..d3aa994 100644 --- a/README.md +++ b/README.md @@ -43,9 +43,8 @@ You don't invoke skills by name. Your coding agent picks them up from what you s lk skills install ``` -That installs all seven skills for the coding agents you pick (Claude Code, Codex, Cursor, GitHub -Copilot, Gemini CLI, and others; the ones it detects are preselected), and adds the LiveKit Docs MCP -server to each one that supports it. `lk skills update` pulls the latest; `lk skills --help` has +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