Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
docs: Add Skills documentation (#57095)
María Craigdd528e3efbb5
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.mdindex 606a75542a5..eca2ca57ae4 100644--- a/docs/src/SUMMARY.md+++ b/docs/src/SUMMARY.md@@ -18,6 +18,7 @@- [Parallel Agents](./ai/parallel-agents.md)- [Inline Assistant](./ai/inline-assistant.md)- [Edit Prediction](./ai/edit-prediction.md)+- [Skills](./ai/skills.md)- [Rules](./ai/rules.md)- [Model Context Protocol](./ai/mcp.md)- [Configuration](./ai/configuration.md)diff --git a/docs/src/ai/agent-panel.md b/docs/src/ai/agent-panel.mdindex 77c052d4841..95588b025f2 100644--- a/docs/src/ai/agent-panel.md+++ b/docs/src/ai/agent-panel.md@@ -234,7 +234,7 @@ terminal_title = ["spinner", "project-name", "run-state", "thread-title"]The agent can search your codebase to find relevant context, but providing it explicitly improves response quality and reduces latency.Add context by typing `@` in the message editor.-You can mention files, directories, symbols, previous threads, rules files, and diagnostics.+You can mention files, directories, symbols, previous threads, skills, and diagnostics.When you paste multi-line code selections copied from a buffer, Zed automatically formats them as @-mentions with the file context.To paste content without this automatic formatting, use {#kb agent::PasteRaw} to paste raw text directly.diff --git a/docs/src/ai/rules.md b/docs/src/ai/rules.mdindex 1fb47aa562d..9258be157e6 100644--- a/docs/src/ai/rules.md+++ b/docs/src/ai/rules.md@@ -3,10 +3,12 @@ title: AI Rules in Zed - .rules, .cursorrules, CLAUDE.mddescription: Configure AI behavior in Zed with .rules files, .cursorrules, CLAUDE.md, AGENTS.md, and the Rules Library for project-level instructions.----# Using Rules {#using-rules}+# Rules {#rules}Rules are prompts that can be inserted either automatically at the beginning of each [Agent Panel](./agent-panel.md) interaction, through `.rules` files available in your project's file tree, or on-demand, through @-mentioning, via the Rules Library.+> **Note:** Starting in Zed v1.4.0, on-demand rules (and the rules library) have been replaced by [Skills](./skills.md). Skills are the recommended way to package reusable agent instructions. Learn more about [the rules -> skills migration](#migrating-to-skills).+## `.rules` filesZed supports including `.rules` files at the root of a project's file tree, and they act as project-level instructions that are auto-included in all of your interactions with the Agent Panel.@@ -30,6 +32,8 @@ It's a full editor with syntax highlighting and all standard keybindings.You can also use the inline assistant right in the rules editor, allowing you to get quick LLM support for writing rules.+> **Note:** Starting in Zed v1.4.0, the rules library has been replaced by [Skills](./skills.md). Skills are the recommended way to package reusable agent instructions. Learn more about [the rules -> skills migration](#migrating-to-skills).+### Opening the Rules Library1. Open the Agent Panel.@@ -66,12 +70,11 @@ All rules in the Rules Library can be set as a default rule, which means they’You can set any rule as the default by clicking the paper clip icon button in the top-right of the rule editor in the Rules Library.-## Migrating from Prompt Library+## Migrating to Skills {#migrating-to-skills}-Previously, the Rules Library was called the "Prompt Library".-The new rules system replaces the Prompt Library except in a few specific cases, which are outlined below.+When you update to Zed v1.4.0, your existing Rules are migrated to Skills automatically:-### Slash Commands in Rules+- **Non-default Rules** become global skills in `~/.agents/skills/`, each with `disable-model-invocation: true`. They remain user-invocable via `/skill-name` or `@`-mention.+- **Default Rules** are appended to your global `AGENTS.md` file (`~/.config/zed/AGENTS.md` on macOS and Linux, `%APPDATA%\Zed\AGENTS.md` on Windows), preserving their behavior of being included in every conversation.-Previously, it was possible to use slash commands (now @-mentions) in custom prompts (now rules).-There is currently no support for using @-mentions in rules files.+A banner in the title bar announces the migration when it runs. Your original Rule data is not deleted, so downgrading to an earlier version of Zed leaves your Rules intact.diff --git a/docs/src/ai/skills.md b/docs/src/ai/skills.mdnew file mode 100644index 00000000000..25ffebc9728--- /dev/null+++ b/docs/src/ai/skills.md@@ -0,0 +1,186 @@+---+title: Agent Skills - Zed+description: Extend Zed's AI agent with reusable, on-demand skill files for specialized tasks.+---++# Skills {#skills}++Skills are reusable instruction packages that give the agent specialized knowledge for specific tasks: test-driven development workflows, document processing, database integrations, or your team's internal coding standards.++A skill is a folder containing a `SKILL.md` file with metadata and instructions. The agent sees a catalog of all installed skills and can load one on demand, or you can invoke any skill directly from the message editor with a slash command.++## Adding Skills {#adding-skills}++### Create Your Own {#create-your-own}++Zed includes a built-in `create-skill` skill that guides the agent through creating a new skill. Invoke it with `/create-skill`, or let the agent pick it up automatically when you ask it to help create a skill.++See [Skill format](#skill-format) below for the folder structure and `SKILL.md` reference.++### From the skills.sh Registry {#from-the-registry}++[skills.sh](https://skills.sh) is a community registry of open-source skills. You'll find skills for popular frameworks, tools, workflows, and more:++- [`find-skills`](https://skills.sh/vercel-labs/skills/find-skills): discover and install skills from the open ecosystem+- [`frontend-design`](https://skills.sh/anthropics/skills/frontend-design): production-grade frontend interfaces with design polish+- [`pdf`](https://skills.sh/anthropics/skills/pdf): PDF text extraction, merging, splitting, form filling, and OCR++To install a skill from it, copy or clone its folder into your global or project-local skills folder.++For example, to install the `frontend-design` skill from GitHub globally:++```sh+cd ~/.agents/skills+git clone --filter=blob:none --sparse https://github.com/anthropics/skills+cd skills+git sparse-checkout set frontend-design+```++For a project-local install, do the same inside your project's `.agents/skills/` folder.++## Using Skills {#using-skills}++By default, the agent picks up skills autonomously. It sees a catalog of every installed skill (name and description) in its system prompt, and calls the `skill` tool when a task matches a skill's description.++When the agent invokes a skill, Zed prompts you to allow or deny it, using the same permission flow as other tools. You can set per-skill defaults in [Tool Permissions](./tool-permissions.md) so you're not prompted for skills you always trust.++### Manual Invocation {#manual-invocation}++You can also load a skill manually:++- **Slash command**: type `/` in the message editor and select a skill by name+- **@-mention**: type `@skill` in the message editor and select a skill from the completion menu++Both inject the skill's instructions as context. The loaded skill appears as a crease button in the thread, which you can click to open the skill file.++### Preventing Autonomous Invocation {#disable-model-invocation}++Add `disable-model-invocation: true` to a skill's frontmatter to stop the agent from picking it up autonomously.+The skill still appears as a slash command, so you stay in control of when it runs.++This is useful for workflows you don't want the agent triggering automatically, like deploy or release procedures.++```yaml+---+name: deploy+description: Deploy the current branch to production.+disable-model-invocation: true+---+```++## Skill Format {#skill-format}++### Folder Structure {#folder-structure}++A skill is a named folder containing a `SKILL.md` file:++```+my-skill/+├── SKILL.md # Required: metadata and instructions+├── scripts/ # Optional: scripts the agent can run+├── references/ # Optional: additional documentation+└── assets/ # Optional: templates and static files+```++The folder name must match the `name` field in `SKILL.md`.++### SKILL.md format {#skill-md-format}++`SKILL.md` starts with YAML frontmatter, followed by Markdown instructions.++**Minimal example:**++```markdown+---+name: my-skill+description: What this skill does and when to use it.+---++## Instructions++Step-by-step instructions for the agent...+```++#### Frontmatter Fields {#frontmatter-fields}++| Field | Required | Description |+| -------------------------- | -------- | -------------------------------------------------------------------------------------------- |+| `name` | Yes | Lowercase letters, numbers, and hyphens only. Max 64 characters. Must match the folder name. |+| `description` | Yes | What the skill does and when to use it. Max 1024 characters. |+| `disable-model-invocation` | No | Set to `true` to hide from the agent's catalog (slash command only). |++> **Tip:** Write descriptions that help the agent recognize when a skill is relevant. Include specific task types and trigger phrases: "Use when handling PDFs, extracting text, or filling forms" is better than "Helps with PDFs."++We plan to include other fields promoted by [the Agent Skills specification](https://agentskills.io/specification) in the near future.++#### Name Validation {#name-validation}++The `name` field must:++- Contain only lowercase letters (`a-z`), numbers, and hyphens+- Not start or end with a hyphen+- Not contain consecutive hyphens (`--`)+- Be 1 to 64 characters++Skills with invalid names fail to load and surface an error in the UI.++### Bundled Resources {#bundled-resources}++Keep the body of `SKILL.md` under 500 lines. Move detailed material to reference files and link to them from the body:++```markdown+See [reference guide](references/REFERENCE.md) for complete API details.++Run the extraction script:+scripts/extract.py+```++The agent loads these files on demand using the `read_file` and `list_directory` tools. Global skills under `~/.agents/skills/` are accessible to the agent even though they're outside your project.++### Writing Effective Instructions {#writing-instructions}++Skills use [progressive disclosure](https://agentskills.io/specification#progressive-disclosure): the agent sees only the name and description until it activates a skill, then loads the full body. Structure your skill to take advantage of this:++- Put the most important instructions near the top of the body+- Keep `SKILL.md` under 500 lines; move detailed references to `references/`+- Scripts that the agent needs to run go in `scripts/`++See the [Agent Skills specification](https://agentskills.io/specification) for the full format reference.++## Where Skills Live {#where-skills-live}++Zed loads skills from two locations:++| Scope | Path | When it applies |+| ------------- | ---------------------------- | ------------------------ |+| Global | `~/.agents/skills/` | Every project |+| Project-local | `<worktree>/.agents/skills/` | Only the current project |++Each skill is a direct child of the skills root. Nesting skills inside subfolders is not supported.++### Project-local Skills and Trust {#project-local-trust}++Project-local skills only load from [trusted worktrees](../worktree-trust.md). Skills from a freshly cloned or untrusted project are excluded from the catalog and slash commands until you grant trust.++This prevents a malicious project from injecting instructions into your agent's system prompt before you've reviewed what the project ships.++### Override Behavior {#override-behavior}++If a global and a project-local skill share the same name, the project-local skill takes precedence. This lets a project customize or replace a global skill for its own context.++### Editing Skill Files {#editing-skill-files}++The agent cannot edit `SKILL.md` files or their bundled resources without your explicit authorization, even in a trusted project. This prevents a compromised conversation from modifying the skills that govern future conversations.++## Limitations {#limitations}++- **Flat layout only.** Skills must be direct children of the skills root. Nested folders like `~/.agents/skills/group/my-skill/` are not discovered.+- **50KB catalog budget.** The total size of all skill names and descriptions is capped at 50KB. Skills that don't fit are dropped from the catalog with a warning in the UI. Keep descriptions concise.+- **No remote registry.** Zed does not fetch skills from URLs or support custom search paths. Skills come from `~/.agents/skills/` and `<worktree>/.agents/skills/` only. Use a symlink if you need to point at another location.+- **Live reload.** Adding, removing, or editing a `SKILL.md` takes effect immediately without restarting your session. Changes to a skill's `name` or `description` invalidate the model's prompt cache for the current session.++## See also++- [Agent Panel](./agent-panel.md)+- [Tool Permissions](./tool-permissions.md)+- [Agent Skills specification](https://agentskills.io/specification)