# How to Migrate from Zed Rules to Zed Agent Skills > Easily migrate from Zed Rules to Zed Agent Skills by importing your SKILL.md file directly. Discover the simple, conversion-free upgrade process for your Zed system. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: migration-guide - Published: 2026-08-22 --- **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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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: ```bash 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) file. As documented in the repository's [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) guide, this ensures your ADHD-specific formatting rules apply automatically without maintaining a separate Rules file. Example structure for your [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md): ```markdown ## 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) directly from the repository at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). Any custom rules you previously used should be moved to [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.