# How i-have-adhd Adapts Its Behavior Across Claude Code, Codex, and Zed Agent Architectures > Discover how i-have-adhd adapts its behavior for Claude Code, Codex, and Zed. Learn about its single source of truth and metadata adapters for consistent ADHD-friendly output across architectures. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: architecture - Published: 2026-07-22 --- **The i-have-adhd skill uses a single source of truth in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) wrapped by thin metadata adapters to deliver consistent ADHD-friendly output across Claude Code, Codex, and Zed without duplicating core logic.** The `i-have-adhd` repository implements a cross-platform agent skill that reshapes LLM output for ADHD accessibility using action-first formatting and visible progress tracking. Rather than maintaining separate codebases for each host environment, the project leverages architecture-specific plugin formats to package the same behavioral rules for Claude Code, OpenAI Codex, and Zed. This approach ensures that numbered steps, clear actions, and eliminated tangents remain consistent regardless of which agent architecture executes the skill. ## The Single Source of Truth Design At the heart of the adaptation strategy sits [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), which defines the universal rules for ADHD-friendly output: lead with actionable steps, use numbered lists, avoid digressions, and maintain visible progress indicators. This file serves as the immutable core that never changes across platforms. According to the repository source code, the platform-specific files function solely as thin adapters that tell the host how to load the skill and which default prompt to inject, ensuring the behavioral logic remains centralized and maintainable. ## Architecture-Specific Packaging Strategies Each agent architecture requires a distinct packaging format to recognize and activate the skill, but all ultimately reference the same [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) content. ### Claude Code Plugin Wrapper For Claude Code, the repository provides [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), which declares the skill name, version, description, and points to the `skills/` directory. This JSON file contains a `defaultPrompt` field that Claude Code automatically prepends to every response generation. When installed, Claude Code reads this JSON at startup, registers the skill, and enforces the rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) through its runtime. The adaptation includes an optional always-on hook mechanism. The file [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) enables session-wide activation when the user creates a trigger file: ```bash touch ~/.claude/.i-have-adhd-always ``` Once this file exists, Claude Code injects the skill for every session without requiring manual invocation. ### Codex Plugin Format OpenAI Codex uses [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json), which provides the same metadata but structured for Codex's expectations, including `interface` fields and a `defaultPrompt` array. Codex scans the plugin file, registers the skill under the "Instructions" capability, and prepends the prompts from `defaultPrompt` before generating any completion. The ADHD-friendly rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) then filter Codex's output without requiring separate rule definitions. ### Zed Skill Directory Zed takes a different approach that requires no JSON wrapper. The skill directory `skills/i-have-adhd/` is copied directly into `~/.config/zed/skills/`. Users then register the agent by adding the skill path to `~/.config/zed/AGENTS.md`: ```bash cp -R i-have-adhd/skills/i-have-adhd ~/.config/zed/skills/ echo "i-have-adhd = i-have-adhd" >> ~/.config/zed/AGENTS.md ``` When invoked via the `/i-have-adhd` command, Zed reads [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) directly from the skills directory and applies the formatting rules to restructure the output. ## Installation Commands by Platform The [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) file documents the precise installation commands for each architecture. While the activation mechanism differs, the invocation command remains identical across all three platforms. **Claude Code installation and activation:** ```bash claude plugin marketplace add ayghri/i-have-adhd claude plugin install i-have-adhd@i-have-adhd ``` **Codex installation:** ```bash codex plugin marketplace add ayghri/i-have-adhd --ref main codex plugin add i-have-adhd@i-have-adhd ``` **Universal invocation (all platforms):** ```text /i-have-adhd ``` When entered, this command triggers the host to inject the default prompt—such as "Use i-have-adhd for this task"—and apply the rules defined in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md). ## Cross-Platform Consistency Mechanisms The adaptation strategy relies on three consistent mechanisms across architectures: 1. **Metadata adapters** – Claude Code and Codex use JSON wrappers ([`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) and [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json)) while Zed uses a simple directory copy, but all point to the same `skills/` folder content. 2. **Default prompt injection** – Each adapter includes a prompt that automatically instructs the LLM to apply i-have-adhd formatting rules for the current task. 3. **Hook-based persistence** – Claude Code supplies [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) to enable always-on behavior via filesystem triggers, while other platforms require manual invocation or configuration file edits. The repository also includes [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) as an example extension, demonstrating how the skill can be described for additional LLM providers using display names and short descriptions, further illustrating the adapter pattern's flexibility. ## Summary - **Single source of truth**: All behavioral rules live in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and remain unchanged across platforms. - **Claude Code adaptation**: Uses [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) with `defaultPrompt` injection and optional always-on hooks via `~/.claude/.i-have-adhd-always`. - **Codex adaptation**: Employs [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) with interface fields and prompt arrays to prepend instructions before generation. - **Zed adaptation**: Requires direct copying to `~/.config/zed/skills/` and registration in `~/.config/zed/AGENTS.md`, reading [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) directly without JSON wrapping. - **Universal invocation**: All three platforms respond to the `/i-have-adhd` command to activate the skill. ## Frequently Asked Questions ### Does i-have-adhd behavior differ between Claude Code and Codex? No. Both agents apply identical ADHD-friendly formatting rules because they reference the same [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) content. The only differences lie in how the plugin metadata is structured—Claude Code uses [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) while Codex uses [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json)—and how prompts are injected into the respective runtimes. ### How do I enable i-have-adhd automatically for every Claude Code session? Create the trigger file `~/.claude/.i-have-adhd-always` using the command `touch ~/.claude/.i-have-adhd-always`. This activates the [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) mechanism, causing Claude Code to automatically inject the skill's default prompt into every conversation without requiring the `/i-have-adhd` command. ### Why does Zed require a different installation method than Claude Code or Codex? Zed's architecture expects skills as raw directories containing [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) rather than wrapped JSON metadata. Instead of parsing a plugin declaration, Zed reads the skill directly from `~/.config/zed/skills/` and requires manual registration in `~/.config/zed/AGENTS.md`. This approach eliminates the need for [`.zed-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.zed-plugin/plugin.json) while maintaining access to the same core rules. ### Can I adapt i-have-adhd for other LLM providers beyond these three agents? Yes. The repository includes [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) as a reference implementation showing how to describe the skill for additional providers. The pattern remains consistent: create a metadata adapter in the format expected by the target platform, point it to the existing [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), and implement the appropriate prompt injection mechanism.