Zed skills. Where they live and how to install them.

What skills are in Zed

Zed's documentation describes skills as reusable instruction packages that give the agent specialised knowledge, such as test-driven development workflows, document processing, database integrations or your team's internal standards. The agent sees a catalogue of installed skills and can load one on demand through a skill tool, or you can invoke any skill from the message editor with a slash command or an @skill mention.

A skill is a folder containing a SKILL.md. Zed documents three frontmatter fields: name (lowercase letters, numbers and hyphens, up to 64 characters, ideally matching the folder name), description (keep it to 1,024 characters or fewer; longer ones still load with a warning) and disable-model-invocation. Zed says it plans to support the other fields in the Agent Skills specification later.

Zed Skills apply to the built-in Zed Agent. External Agents and Terminal Threads may have their own skill systems, which you configure in that agent or CLI.

Where Zed looks for skills

Each skill must be a direct child of the skills folder. Nesting skills in subfolders, such as ~/.agents/skills/group/my-skill/, is not supported. Zed does not support custom search paths and does not load skills from remote locations at runtime, so use a symlink if a skill lives elsewhere. A project-local skill overrides a global one with the same name. Project skills load only from trusted worktrees, so a freshly cloned or untrusted project's skills stay out of the catalogue until you grant trust.

Install a skill

The examples use frontend-design from anthropics/skills, located at skills/frontend-design.

Option 1: copy the folder

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
mkdir -p ~/.agents/skills
cp -r skills-src/skills/frontend-design ~/.agents/skills/frontend-design
rm -rf skills-src

For a project-local skill, copy into .agents/skills/ in the repository instead. Zed's own page describes installing a registry skill the same way: copy the folder into ~/.agents/skills/ for global use, or into the project's .agents/skills/ for project use.

Option 2: the skills CLI

npx skills add anthropics/skills --skill frontend-design -a zed

This installs into .agents/skills/ in the project. Add -g for ~/.agents/skills/.

Option 3: import from a GitHub Markdown file

Open the command palette and run agent: create skill from url. If your clipboard holds a supported GitHub .md URL, Zed pre-fills and fetches it. For example:

https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

This imports a single Markdown file, so bundled scripts and reference files are not fetched. Copy those separately, or use option 1 for skills that rely on them.

Other ways to add a skill

Zed includes a built-in create-skill skill, which you invoke with /create-skill. You can also open the Skills Manager from the Agent Panel, or use the Create Skill button on the AI > Skills settings page. A skill can be shared with a zed://skill link that embeds the full SKILL.md. Opening the link shows a Create Skill page, and nothing is written to disk until you save.

Check that it loaded

Open the Settings Editor and go to AI > Skills (or agent.skills). The User tab lists global skills and each Project tab lists that project's skills, with actions to copy a share link, open the file or delete the folder. In the message editor, type / and select the skill, or type @skill and choose it from the menu. Adding, removing or editing a SKILL.md takes effect immediately, so no restart is needed.

Update and remove

• Remove: use Delete on the skill's row in Settings, or delete the folder, or run npx skills remove frontend-design.
• Update: copy a newer version of the folder over the old one. Changing a skill's name or description invalidates the model's prompt cache for the current session.

Troubleshooting

• A skill is missing from the list: confirm it is a direct child of ~/.agents/skills/ or .agents/skills/, and that the folder contains SKILL.md.
• A project skill does not load: the worktree may not be trusted. Grant trust, then check again.
• A skill with an invalid name fails to load and shows an error in the UI. Names cannot start or end with a hyphen or contain consecutive hyphens.
• The catalogue is full: the combined size of all skill names and descriptions is capped at 50KB, and skills that do not fit are dropped with a warning. Shorten descriptions.
• The agent pauses before using a skill: Zed asks you to allow or deny a skill you created or installed when the agent invokes it, so look for the permission prompt, or set per-skill defaults in Tool Permissions.

Safety

Zed documents several guards. Project skills load only from trusted worktrees, shared links write nothing until you save, and the agent cannot edit SKILL.md files or their resources without your explicit authorisation. You still decide what to install, so read SKILL.md and any scripts first, and be careful granting trust to a repository you have just cloned.