agentleFS
14ag14ag/claude-skills/zed-extension/SKILL.md

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.

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
  1. Distinctive:

    All Zed extension documentation lives under one root.

    line 14
  2. Very specific:

    Ask the user which of these they are building.

    line 33
  3. Distinctive:

    Every extension is its own Git repo.

    line 71
  4. Distinctive:

    Always use the latest version from: https://crates.io/crates/zed_extension_api

    line 122
  5. Distinctive:

    If a published version of the same extension is installed, Zed uninstalls it automatically before loading the dev version.

    line 168
  6. Very specific:

    All required extension.toml fields are filled

    line 184

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:


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.

TypeNeeds Rust + WASMNeeds extension.toml sectionPrimary Doc
Language (LSP + Tree-sitter)Yes[language_servers.] + [languages.]/docs/extensions/languages
Slash CommandYes[slash_commands.*]/docs/extensions/slash-commands
MCP ServerYes[context_servers.*]/docs/extensions/mcp-extensions
ThemeNo(none - JSON only)/docs/extensions/themes
Icon ThemeNo(none - JSON only)/docs/extensions/icon-themes
SnippetNo(none - JSON only)/docs/extensions/snippets
DebuggerYes[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-wasip1

Install the Zed CLI for local testing:


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 extensions

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

  1. Open Zed
  2. Open Command Palette -> "zed: extensions"
  3. Click "Install Dev Extension"
  4. 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)
  • 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

SymptomCauseFix
Dev extension silently fails to loadRust not installed via rustupReinstall via rustup
"wasm32-wasip1 target not found"Target not addedrustup target add wasm32-wasip1
PR CI fails with license errorNo LICENSE file in repo rootAdd an accepted open-source license
Extension ID rejectedContains "zed" or "extension"Rename the id field
Language server not found at runtimeShipped binary instead of download logicUse zed.download_file() in Rust code

Reference Files in This Skill

  • references/extension-types.md - Per-type constraints and direct doc links
  • references/design-log.md - Prompt formulation rationale

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.