Zed — Skills
- File format
- Markdown
- Discovery path
.agents/skills- Global install path
~/.agents/skills- Syllago install method
- Symlink, Direct copy
- Symlink support
- Yes
- Native frontmatter fields
name,description,disable-model-invocation
Features
How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.
Fields
Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.
| Provider field | Conversion | Canonical key | Summary |
|---|---|---|---|
description | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | description | yaml frontmatter key: description (required). States what the skill does and when to use it; the agent uses it to decide when to auto-invoke. Keep under 1024 bytes — longer descriptions still load but surface a warning. |
disable-model-invocation | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | disable_model_invocation | yaml frontmatter key: disable-model-invocation (optional bool, default false). When true the skill is hidden from the agent's autonomous catalog but stays invocable by the user via slash command or @-mention — useful for deploy/release procedures you do not want the agent triggering. |
name | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | display_name | yaml frontmatter key: name (required). Lowercase letters, numbers, and hyphens only; 1-64 characters; no leading/trailing or consecutive hyphens. Should match the skill's folder name and doubles as the skill identifier; skills with invalid names fail to load. |
Other features
Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.
| Feature | Conversion | Summary |
|---|---|---|
auto_invocable | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | By default the agent picks up skills autonomously: it sees a catalog of every installed skill (name + description) in its system prompt and calls the skill tool when a task matches a skill's description. Semantic description matching, opt-out via disable-model-invocation — functionally the canonical auto_invocable capability. |
canonical_filename | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | SKILL.md is the required fixed filename inside each skill folder (starts with YAML frontmatter, followed by Markdown instructions). |
global_scope | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | Global skills live in ~/.agents/skills/<name>/SKILL.md and apply to every project. The agent can read global skill resources even though they are outside the current project. |
project_scope | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | Project-local skills live in <worktree>/.agents/skills/<name>/SKILL.md and apply only to the current project. They load only from trusted worktrees — skills from a freshly cloned or untrusted project are excluded from the catalog and slash commands until trust is granted. |
skill_bundled_resources | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | A skill folder may co-locate scripts/ (scripts the agent can run), references/ (additional documentation), and assets/ (templates and static files) alongside SKILL.md. The agent loads them on demand via the read_file and list_directory tools; the SKILL.md body links to them (progressive disclosure). |
user_invocable | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | All installed skills are user-invocable: type / in the message editor and select a skill by name, or @skill to pick one from the completion menu. Both inject the skill's instructions as context (shown as a clickable crease button). disable-model-invocation: true removes only the model's autonomous invocation, leaving the skill user-invocable. |
| 50KB catalog budget | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | The total size of all skill names and descriptions is capped at 50KB. Skills that do not fit are dropped from the catalog with a UI warning, so descriptions must stay concise (individual descriptions are also soft-capped at 1024 bytes). |
| Agent edit protection for skill files | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | The agent cannot edit SKILL.md files or their bundled resources without explicit user authorization, even in a trusted project. This prevents a compromised conversation from modifying the skills that govern future conversations. |
| Built-in skill creator and URL import | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Zed ships a built-in create-skill skill (invoke via /create-skill) that walks you through authoring, plus a Skills Manager (cmd-alt-l|ctrl-alt-l) and an 'agent: create skill from url' command that imports a skill from a supported GitHub Markdown URL. The creator saves to the scope of the selected settings tab (User = global, Project = project-local). |
| Flat skills layout (no nesting) | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Each skill must be a direct child of the skills root. Nested folders like ~/.agents/skills/group/my-skill/ are not discovered — a stricter layout than providers that walk nested skill directories. |
| Live reload of skill files | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Adding, removing, or editing a SKILL.md takes effect immediately without restarting the session. Changing a skill's name or description invalidates the model's prompt cache for the current session. |
| Per-skill tool-permission prompt | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | When the agent invokes a user-created or installed skill, Zed prompts allow/deny using the same permission flow as other tools; skills built into Zed do not prompt. Per-skill defaults can be set in Tool Permissions to avoid repeated prompts for trusted skills. |
| Project-local trust gating | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Project-local skills load only from trusted worktrees. Skills from a freshly cloned or untrusted project are excluded from the catalog and slash commands until you grant trust — preventing a malicious project from injecting instructions into the agent's system prompt before you have reviewed what it ships. |
| Project-over-global name override | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | If a global and a project-local skill share the same name, the project-local skill takes precedence — letting a project customize or replace a global skill for its own context. |
| skills.sh community registry | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Skills can be installed from skills.sh, a community registry of open-source skills (e.g. find-skills, frontend-design, pdf). Install by copying the skill's folder into ~/.agents/skills/ (global) or the project's .agents/skills/ (project-local). The built-in find-skills skill discovers and installs skills from the open ecosystem. |
| Slash-command and @-mention invocation | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Beyond autonomous invocation, a skill can be loaded manually: type / and select it by name, or type @skill and pick it from the completion menu. Both inject the skill's instructions as context; the loaded skill appears as a crease button in the thread that opens the skill file when clicked. |
| Zed Agent path boundary | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Zed Skills apply to the Zed Agent only. External Agents (over the Agent Client Protocol) and Terminal Threads (native CLIs/TUIs) may have their own native skills, prompts, or instruction systems, configured in the external agent or CLI rather than here. |
| zed://skill share links | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | The Skills settings page can copy a self-contained zed://skill?data=... link that embeds the full SKILL.md contents (base64url-encoded). A recipient opening the link gets a pre-filled 'Create Skill' page; nothing is written to disk until they explicitly save, so a shared link can never silently install instructions. |
Sources
| Source |
|---|
| https://zed.dev/docs/ai/skills |