How i-have-adhd Adapts Its Behavior Across Claude Code, Codex, and Zed Agent Architectures

The i-have-adhd skill uses a single source of truth in 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, 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 content.

Claude Code Plugin Wrapper

For Claude Code, the repository provides .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 through its runtime.

The adaptation includes an optional always-on hook mechanism. The file hooks/hooks.json enables session-wide activation when the user creates a trigger file:

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, 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 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:

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 directly from the skills directory and applies the formatting rules to restructure the output.

Installation Commands by Platform

The 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:

claude plugin marketplace add ayghri/i-have-adhd
claude plugin install i-have-adhd@i-have-adhd

Codex installation:

codex plugin marketplace add ayghri/i-have-adhd --ref main
codex plugin add i-have-adhd@i-have-adhd

Universal invocation (all platforms):

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

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 and .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 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 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 and remain unchanged across platforms.
• Claude Code adaptation: Uses .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 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 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 content. The only differences lie in how the plugin metadata is structured—Claude Code uses .claude-plugin/plugin.json while Codex uses .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 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 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 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 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, and implement the appropriate prompt injection mechanism.

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