How the i-have-adhd Skill Is Adapted for Different Agent Runtimes

The i-have-adhd skill uses a single markdown file (SKILL.md) as the source of truth, with lightweight runtime-specific adapters that load the ADHD-friendly rules into Pi, OMP, Claude Code, Codex, OpenCode, Gemini, Kimi, and Qwen.

The ayghri/i-have-adhd repository provides a unified approach to ADHD-friendly AI output formatting. Instead of duplicating logic across platforms, the i-have-adhd skill centralizes its rule definitions in one canonical file while using framework-specific manifests and TypeScript extensions to inject those rules into diverse agent runtimes.

Single Source of Truth

Every adapter points to SKILL.md located at skills/i-have-adhd/SKILL.md. This file contains the complete set of output guidelines formatted for ADHD accessibility, including structure preferences, attention-management cues, and cognitive load reduction rules.

The separation of concerns ensures that behavioral updates only require editing one file. All runtime adapters consume this same document, stripping front-matter programmatically via the shared loadRules() function before injecting the content into their respective contexts.

Runtime-Specific Adapter Implementations

Each supported agent framework implements a lightweight shim that understands how to register commands and manage session state according to that runtime's extension API.

Pi and OMP (TypeScript Extension)

The primary reference implementation lives in extensions/i-have-adhd.ts. This TypeScript module registers the /i-have-adhd command and manages session persistence through STATE_ENTRY_TYPE entries.

Key behaviors in the Pi/OMP adapter:

• Command registration: Accepts /i-have-adhd [on|off] with empty arguments toggling current state
• Rule synchronization: Uses syncContext to maintain alignment between the flag and model context
• Message injection: Sends hidden custom messages with types RULES_MESSAGE_TYPE and DISABLED_MESSAGE_TYPE via pi.sendMessage, keeping the UI clean while updating the system prompt

// Toggling the mode from a Pi / OMP session
await pi.runCommand("i-have-adhd");          // flips the current state
await pi.runCommand("i-have-adhd on");       // forces enable
await pi.runCommand("i-have-adhd off");      // forces disable

Claude Code

The Claude Code runtime uses manifest-based discovery. The file .claude-plugin/plugin.json declares the skill metadata:

{
  "name": "i-have-adhd",
  "description": "Shape Claude Code output for an ADHD reader…"
}

Claude Code automatically loads this manifest and exposes the command, delegating the actual rule content back to the shared TypeScript logic where available.

Codex

Similar to Claude Code, the Codex adapter resides in .codex-plugin/plugin.json with an accompanying marketplace.json for distribution metadata. Codex reads this manifest to expose the skill under the same name and description, ensuring consistent UX across OpenAI's tool ecosystem.

OpenCode

OpenCode requires both a manifest and an executable module. The repository provides:

• .opencode/plugins/i-have-adhd.mjs – JavaScript module registering the command with the OpenCode runtime
• .opencode/command/i-have-adhd.md – Command description documentation

The module reuses the same flag logic and session state management found in the Pi extension, calling loadRules() to fetch the canonical SKILL.md content.

Gemini, Kimi, and Qwen

These Chinese and multimodal AI platforms consume individual JSON manifests:

• gemini-extension.json for Google's Gemini runtime
• kimi.plugin.json for the Moonshot Kimi agent
• qwen-extension.json for Alibaba's Qwen models

Each manifest lists the skill name and description in the format expected by that specific runtime. While the entry points differ, they delegate rule-loading to the shared TypeScript extension where the runtime environment supports it.

Core Implementation Logic

All adapters share four consistent behaviors regardless of the host framework:

1. loadRules() – Reads SKILL.md and strips YAML front-matter to extract pure rule text
2. Session persistence – Stores enablement state using STATE_ENTRY_TYPE to survive context resets
3. Context injection – Injects rules as hidden system messages (types RULES_MESSAGE_TYPE and DISABLED_MESSAGE_TYPE) that affect model output without cluttering the chat interface
4. User interface – Exposes /i-have-adhd [on|off] with smart toggling when no argument is provided

This unified approach means fixing a rule in SKILL.md instantly updates behavior across Pi, Claude Code, Codex, and all other supported platforms.

Always-On Configuration

For users who want the skill active by default, the repository includes hooks/always-on.mjs (and related scripts). These hooks check for the existence of a .i-have-adhd-always flag file in the workspace root using existsSync(alwaysOnFlag).

When this file is present, the extension automatically enables ADHD-friendly formatting on startup without requiring manual command invocation:

# Enabling "always-on" for any runtime that respects the hook

touch .i-have-adhd-always

This mechanism works across all runtime adapters that implement the hook check, providing seamless integration for persistent ADHD accessibility.

Summary

• The i-have-adhd skill maintains one canonical rule file (SKILL.md) that all runtimes consume
• Pi and OMP use the TypeScript extension at extensions/i-have-adhd.ts for full command and state management
• Claude Code, Codex, Gemini, Kimi, and Qwen use JSON manifests (.claude-plugin/plugin.json, .codex-plugin/plugin.json, gemini-extension.json, etc.) for runtime discovery
• OpenCode combines a JavaScript module with markdown documentation for its plugin system
• All implementations share core functions: loadRules(), syncContext, and custom message type injection (RULES_MESSAGE_TYPE, DISABLED_MESSAGE_TYPE)
• Always-on mode activates via a .i-have-adhd-always file checked by hooks/always-on.mjs

Frequently Asked Questions

How does the i-have-adhd skill maintain consistency across different AI platforms?

The skill stores all behavioral rules in a single SKILL.md file. Each runtime adapter calls loadRules() to fetch this content, ensuring that updates propagate instantly to Claude Code, Codex, Pi, and other supported agents without code duplication.

What files are required to add support for a new agent runtime?

You need a runtime-specific manifest (such as plugin.json or extension.json) and optionally a lightweight adapter script that calls the shared loadRules() function. The core logic in extensions/i-have-adhd.ts can be reused for TypeScript-based runtimes, while JSON-only environments simply point to the skill metadata.

Can the i-have-adhd skill be enabled automatically without typing commands?

Yes. Create a file named .i-have-adhd-always in your project root. The hooks/always-on.mjs script detects this file via existsSync() and triggers the enablement logic on extension startup, applying ADHD-friendly formatting immediately.

Which runtimes use the TypeScript extension versus just JSON manifests?

Pi and OpenCode use the full TypeScript/JavaScript extension (extensions/i-have-adhd.ts and .opencode/plugins/i-have-adhd.mjs) for dynamic command handling. Claude Code, Codex, Gemini, Kimi, and Qwen use static JSON manifests that declare the skill but rely on the runtime's extension loading mechanism to handle the actual rule injection.

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