mirror of
https://github.com/zed-industries/zed.git
synced 2026-06-01 03:14:56 +07:00
docs: Add Skills documentation (#57095)
Adds documentation for the new Skills feature, which replaces Rules starting in Zed v1.4.0. ## Changes - **New page**: `docs/src/ai/skills.md` — covers what skills are, finding and installing skills from skills.sh, using skills via slash commands and model invocation, creating a skill (folder structure, SKILL.md format, frontmatter fields, bundled resources), where skills live (global vs project-local), security model, and limitations - **Updated**: `docs/src/ai/rules.md` — added deprecation notice pointing to Skills - **Updated**: `docs/src/SUMMARY.md` — added Skills entry above Rules in the AI section - **Updated**: `docs/src/ai/agent-panel.md` — replaced reference to "rules files" with "skills" in the Adding Context section Release Notes: - Added documentation for the Skills feature --------- Co-authored-by: zed-zippy[bot] <234243425+zed-zippy[bot]@users.noreply.github.com> Co-authored-by: Danilo Leal <daniloleal09@gmail.com>
This commit is contained in:
María Craig
GitHub
parent
a4c6a8392d
commit
dd528e3efb
4 changed files with 198 additions and 8 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -3,10 +3,12 @@ title: AI Rules in Zed - .rules, .cursorrules, CLAUDE.md
|
|||
description: 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` files
|
||||
|
||||
Zed 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 Library
|
||||
|
||||
1. 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.
|
||||
|
|
|
|||
186
docs/src/ai/skills.md
Normal file
186
docs/src/ai/skills.md
Normal file
|
|
@ -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)
|
||||
Loading…
Reference in a new issue