How to Migrate from Zed Rules to Zed Agent Skills

Zed has deprecated its legacy Rules system in favor of Agent Skills, allowing you to migrate simply by importing the SKILL.md file directly without any conversion steps.

If you are using Zed editor with the ayghri/i-have-adhd repository, you need to migrate from Zed Rules to Zed Agent Skills to access the latest ADHD-focused prompting features. The new framework eliminates manual rule conversion by reading the SKILL.md file natively. This guide walks you through the exact steps to transition your workflow using the canonical skill definition.

Why Zed Rules Were Replaced by Agent Skills

Zed Rules were a legacy method for defining agent behavior that required manual maintenance and lacked standardization. The Agent Skills framework provides a single source of truth through the SKILL.md file that all Zed agents consume directly. According to the ayghri/i-have-adhd source code, this change removes transformation steps entirely—agents now read the skill definition natively from skills/i-have-adhd/SKILL.md.

Step-by-Step Migration to Zed Agent Skills

Follow these exact steps to import the i-have-adhd skill using Zed's native Skills Manager.

Import the Skill from the Repository URL

Open Zed's Agent Panel → Skills Manager and click Create skill from URL, or run the command agent: create skill from url from the command palette. Paste the following URL into the input field:

https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md

Choose either User scope for global availability across all projects, or Project scope to restrict the skill to your current workspace. Click Save to import the skill definition directly from the canonical source file.

Alternative: Manual Installation via File System

If you prefer command-line installation or need to customize the skill locally, clone the repository and copy the skill folder to Zed's configuration directory:

git clone https://github.com/ayghri/i-have-adhd
cp -R i-have-adhd/skills/i-have-adhd ~/.config/zed/skills/

This method places the skill files in ~/.config/zed/skills/i-have-adhd/, making them available to the Agent without requiring URL imports.

Handling Existing Zed Rules and Customizations

If you previously maintained custom rules in a separate Rules file, there is no automatic conversion required. Instead, migrate your custom behavior to Zed's persistent AGENTS.md file.

Persisting Rules in AGENTS.md

Copy any custom rule definitions you want to keep as always-on behavior into ~/.config/zed/AGENTS.md for global settings, or into a project-local AGENTS.md file. As documented in the repository's AGENTS.md guide, this ensures your ADHD-specific formatting rules apply automatically without maintaining a separate Rules file.

Example structure for your AGENTS.md:

## Output style

The reader has ADHD. Shape every response so it can be acted on:
1. Lead with the answer or next action
2. Use bullet points for scannable content
3. Keep paragraphs under 3 sentences

Verifying and Updating Your Migration

After installation, verify the skill is active by opening the Skills Manager and looking for "i-have-adhd" in your skill list. Alternatively, type /i-have-adhd in the Agent Panel to invoke the skill directly.

When the upstream ayghri/i-have-adhd repository updates, refresh your skill by re-importing the URL in the Skills Manager, or by pulling the latest changes and copying the updated skills/i-have-adhd folder to your configuration directory again.

Summary

• No conversion needed: Zed Agent Skills read SKILL.md files natively, eliminating the old Rules transformation step.
• Import via URL: Use https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md in the Skills Manager with either User or Project scope.
• Command-line option: Clone the repo and copy skills/i-have-adhd/ to ~/.config/zed/skills/ for manual installation.
• Preserve custom rules: Move legacy rule snippets to AGENTS.md for always-on behavior.
• Verify installation: Check the Skills Manager or type /i-have-adhd in the Agent Panel.

Frequently Asked Questions

Do I need to convert my old Zed Rules file to a new format?

No. The migration from Zed Rules to Agent Skills does not require file conversion. The new framework reads the canonical SKILL.md directly from the repository at skills/i-have-adhd/SKILL.md. Any custom rules you previously used should be moved to AGENTS.md for persistent application.

Where is the SKILL.md file located in the repository?

The canonical skill definition is located at skills/i-have-adhd/SKILL.md in the ayghri/i-have-adhd repository. This path serves as the single source of truth that Zed's Agent reads when you import the skill via URL or manual installation.

Can I use the i-have-adhd skill across all my Zed projects?

Yes. When importing via the Skills Manager, select User scope to make the skill available globally in ~/.config/zed/skills/. Alternatively, choose Project scope to restrict it to a specific workspace. You can also manually copy the skill folder to ~/.config/zed/skills/ for system-wide access.

How do I update the skill when the repository changes?

To update, simply re-import the URL in Zed's Skills Manager, which pulls the latest version of SKILL.md from the main branch. If you installed manually via git, run git pull in your local clone and copy the updated skills/i-have-adhd folder to ~/.config/zed/skills/ again.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}