zed/docs/src/ai/skills.md

title	description
Agent Skills - Zed	Extend Zed's AI agent with reusable, on-demand skill files for specialized tasks.

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

Create your own

Zed includes a built-in create-skill skill — invoke it with /create-skill and the agent walks you through the process.

You can also open the Skill Creator from the Agent Panel using {#kb agent::OpenRulesLibrary}, or by clicking ... and selecting Skills. Outside the panel, use the {#action agent::OpenSkillCreator} action from the command palette. It opens a window where you fill in the skill's name, description, scope (global or project-local), body, and optionally toggle disable-model-invocation.

Lastly, it's also possible to add a skill through importing it from an existing GitHub Markdown file. Open the command palette and look for the {#action agent::CreateSkillFromUrl} action. If your clipboard contains a supported GitHub .md URL, Zed pre-fills and fetches it automatically.

See Skill format below for the full format reference.

From the skills.sh Registry

skills.sh is a community registry of open-source skills. You'll find skills for popular frameworks, tools, workflows, and more:

• find-skills: discover and install skills from the open ecosystem
• frontend-design: production-grade frontend interfaces with design polish
• pdf: PDF text extraction, merging, splitting, form filling, and OCR

To install a skill, copy the skill's folder into ~/.agents/skills/ for global use, or into your project's .agents/skills/ folder for project-local use.

Managing Skills

Open the Settings Editor (Cmd+, on macOS, Ctrl+, on Linux/Windows) and navigate to AI > Skills, or go directly to agent.skills.

The User tab shows your global skills. The Project tab shows skills for the current project.

For each skill you can:

• Copy Share Link — copies a zed://skill link that embeds the skill, ready to send to someone else (see Sharing Skills)
• Open — opens the skill's SKILL.md file in the editor
• Delete — removes the skill folder from disk

If no skills are installed, the page shows a Create a Skill button that opens the Skill Creator.

Sharing Skills

You can hand a skill to a teammate without hosting it anywhere. In the Skills settings page, click the link icon on a skill row to copy a zed://skill?data=… link to your clipboard. The link is self-contained: it embeds the full SKILL.md contents (base64url-encoded), so the recipient doesn't need access to your project or any registry.

When someone opens that link (for example by pasting it into their browser or clicking it in a chat), Zed launches the Skill Creator pre-filled with the shared skill. The recipient can review the name, description, and full body, choose a scope (global or project-local), and click Save to install it. Nothing is written to disk until they explicitly save, so a shared link can never silently install instructions into someone's agent.

Managing Skills

Open the Settings Editor (Cmd+, on macOS, Ctrl+, on Linux/Windows) and navigate to AI > Skills, or go directly to agent.skills.

The User tab shows your global skills. The Project tab shows skills for the current project.

For each skill you can:

• Open — opens the skill's SKILL.md file in the editor
• Delete — removes the skill folder from disk

If no skills are installed, the page shows a Create a Skill button that opens the Skill Creator.

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 so you're not prompted for skills you always trust.

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

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.

---
name: deploy
description: Deploy the current branch to production.
disable-model-invocation: true
---

Skill Format

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 starts with YAML frontmatter, followed by Markdown instructions.

Minimal example:

---
name: my-skill
description: What this skill does and when to use it.
---

## Instructions

Step-by-step instructions for the agent...

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 in the near future.

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

Keep the body of SKILL.md under 500 lines. Move detailed material to reference files and link to them from the body:

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

Skills use 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 for the full format reference.

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 skills only load from trusted worktrees. 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

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

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

• 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
• Tool Permissions
• Agent Skills specification