zed-extension
Skill0 starsChanged 3 months agoMITView on GitHub
Use this skill whenever the user wants to build, scaffold, debug, publish, or understand how to develop an extension for the Zed code editor. Trigger phrases include "build a Zed extension", "create a Zed plugin", "Zed language support extension", "Zed theme extension", "Zed MCP extension", "Zed debugger extension", "Zed slash command", "zed_extension_api", "extension.toml Zed", "publish Zed extension", "Zed WASM extension". Do NOT trigger for general Rust questions, VSCode extensions, or Zed editor configuration that does not involve building an extension.
In this repository24 other files it gives its agents.
- corporate-espionageSkill
- dispatching-parallel-agentsSkill
- epub-readerSkill
- executing-plansSkill
- finishing-a-development-branchSkill
- github-raw-readerSkill
- magisk-moduleSkill
- notepadpp-plugin-skillSkill
- planningSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- reviewSkill
- skill-creator2Skill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- technical-writerSkill
- test-driven-developmentSkill
- text-humanizerSkill
- using-git-worktreesSkill
- using-superpowersSkill
- verification-before-completionSkill
- windows-diagnosticsSkill
- writing-plansSkill
- zed-themeSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
All Zed extension documentation lives under one root.
- Very specific: line 33
Ask the user which of these they are building.
- Distinctive: line 71
Every extension is its own Git repo.
- Distinctive: line 122
Always use the latest version from: https://crates.io/crates/zed_extension_api
- Distinctive: line 168
If a published version of the same extension is installed, Zed uninstalls it automatically before loading the dev version.
- Very specific: line 184
All required extension.toml fields are filled
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Zed Extension Builder
This skill routes you to the correct official Zed documentation and outlines the build process for each extension type. It does not duplicate the docs - it maps the workflow and sends you to the authoritative source for each step.
Canonical Doc Index
All Zed extension documentation lives under one root. Bookmark this:
- Overview: https://zed.dev/docs/extensions
- Developing Extensions (primary reference): https://zed.dev/docs/extensions/developing-extensions
- Language Extensions: https://zed.dev/docs/extensions/languages
- Slash Command Extensions: https://zed.dev/docs/extensions/slash-commands
- MCP Server Extensions: https://zed.dev/docs/extensions/mcp-extensions
- Theme Extensions: https://zed.dev/docs/extensions/themes
- Icon Theme Extensions: https://zed.dev/docs/extensions/icon-themes
- Snippet Extensions: https://zed.dev/docs/extensions/snippets
- Debugger Extensions: https://zed.dev/docs/extensions/debuggers
- Rust API Crate (zed_extension_api): https://crates.io/crates/zed_extension_api
- Extension Registry Repo: https://github.com/zed-industries/extensions
- Architecture Deep Dive (WASM + WIT): https://zed.dev/blog/zed-decoded-extensions
Step 1 - Identify Extension Type
Ask the user which of these they are building. Route to references/extension-types.md
for a decision table and per-type constraints.
| Type | Needs Rust + WASM | Needs extension.toml section | Primary Doc |
| Language (LSP + Tree-sitter) | Yes | [language_servers.] + [languages.] | /docs/extensions/languages |
| Slash Command | Yes | [slash_commands.*] | /docs/extensions/slash-commands |
| MCP Server | Yes | [context_servers.*] | /docs/extensions/mcp-extensions |
| Theme | No | (none - JSON only) | /docs/extensions/themes |
| Icon Theme | No | (none - JSON only) | /docs/extensions/icon-themes |
| Snippet | No | (none - JSON only) | /docs/extensions/snippets |
| Debugger | Yes | [debugger_adapters.*] | /docs/extensions/debuggers |
Rules enforced at publish time:
- Themes and icon themes must NOT be bundled with language or code extensions
- Language and debugger extensions must NOT ship the language server binary
- The extension must download it at runtime or locate it from the user PATH
- Extension IDs must not contain the words "zed" or "extension"
Step 2 - Set Up the Dev Environment
Prerequisite: Rust installed via rustup only. Homebrew-installed Rust will break dev extension loading.
rustup target add wasm32-wasip1Install the Zed CLI for local testing:
- macOS / Linux: https://zed.dev/docs/getting-started
- Windows (WSL): https://zed.dev/docs/getting-started
Step 3 - Scaffold the Extension Repository
Every extension is its own Git repo. Minimum structure:
my-extension/
extension.toml # manifest - required for all types
Cargo.toml # required only for Rust-based extensions
src/
lib.rs # required only for Rust-based extensions
languages/
my-language/
config.toml # language config
highlights.scm # Tree-sitter highlight queries
themes/ # for theme-only extensions
snippets/ # for snippet extensionsextension.toml Mandatory Fields
[extension]
id = "my-extension-id" # unique lowercase kebab-case
name = "My Extension"
version = "0.1.0"
schema_version = 1
authors = ["Your Name <you@example.com>"]
description = "What it does"
repository = "https://github.com/you/my-extension"For the full field reference see: https://zed.dev/docs/extensions/developing-extensions
Step 4 - Write the Rust Extension Code (Rust-based types only)
Cargo.toml minimum
[package]
name = "my-extension"
version = "0.1.0"
edition = "2021"
[lib]
crate-type = ["cdylib"]
[dependencies]
zed_extension_api = "0.1.0"Always use the latest version from: https://crates.io/crates/zed_extension_api
src/lib.rs minimum
use zed_extension_api as zed;
struct MyExtension;
impl zed::Extension for MyExtension {
fn new() -> Self {
MyExtension
}
}
zed::register_extension!(MyExtension);Then implement only the trait methods your extension needs. Full trait method list: https://docs.rs/zed_extension_api/latest/zed_extension_api/trait.Extension.html
Step 5 - Type-Specific Implementation
Route to references/extension-types.md for:
- Language extension: grammar + LSP command wiring
- Slash command: run_slash_command impl + output sections
- MCP server: context_server_command impl
- Debugger: debugger adapter command impl
Each section in that file links directly to the Zed doc page for that type.
Step 6 - Test Locally as a Dev Extension
- Open Zed
- Open Command Palette -> "zed: extensions"
- Click "Install Dev Extension"
- Select your extension directory
For logs: Command Palette -> "zed: open log"
For verbose debug output: launch from terminal with zed --foreground
If a published version of the same extension is installed, Zed uninstalls it automatically before loading the dev version.
Step 7 - Publish to the Registry
Publishing requires forking the central registry repo and opening a PR.
Full publishing walkthrough: https://zed.dev/docs/extensions/developing-extensions#publishing-your-extension
Pre-publish checklist:
- Extension ID is unique and does not contain "zed" or "extension"
- A LICENSE file is present at the repo root (required since October 2025)
- Accepted licenses listed at: https://zed.dev/docs/extensions/developing-extensions
- All required extension.toml fields are filled
- Version string matches between extension.toml and extensions.toml entry
- Themes/icon themes are not bundled with code extensions
- Language server binary is not shipped inside the extension
Failure Modes and Fixes
| Symptom | Cause | Fix |
| Dev extension silently fails to load | Rust not installed via rustup | Reinstall via rustup |
| "wasm32-wasip1 target not found" | Target not added | rustup target add wasm32-wasip1 |
| PR CI fails with license error | No LICENSE file in repo root | Add an accepted open-source license |
| Extension ID rejected | Contains "zed" or "extension" | Rename the id field |
| Language server not found at runtime | Shipped binary instead of download logic | Use zed.download_file() in Rust code |
Reference Files in This Skill
references/extension-types.md- Per-type constraints and direct doc linksreferences/design-log.md- Prompt formulation rationale
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

