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

> Discover how the i-have-adhd skill adapts to various agent runtimes like Pi, OMP, Claude Code, and Gemini. Learn about its single markdown source and lightweight adapters.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-23

---

**The i-have-adhd skill uses a single markdown file ([`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) located at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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

```typescript
// 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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) declares the skill metadata:

```json
{
  "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`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) with an accompanying [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) content.

### Gemini, Kimi, and Qwen

These Chinese and multimodal AI platforms consume individual JSON manifests:

- [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) for Google's Gemini runtime
- [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json) for the Moonshot Kimi agent
- [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)) that all runtimes consume
- **Pi and OMP** use the TypeScript extension at [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json), [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) or [`extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/extension.json)) and optionally a lightweight adapter script that calls the shared `loadRules()` function. The core logic in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.