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 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.

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

See Skill format below for the folder structure and SKILL.md 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 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:

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

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

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:

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