# How to Add i-have-adhd Support to a New AI Assistant Platform

> Learn how to add i-have-adhd support to your AI assistant platform. Integrate the portable skill, adapter, and JSON manifest for enhanced functionality.

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

---

**You can add i-have-adhd support to a new AI assistant platform by wiring the repository's portable skill—consisting of the [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) rule set, the [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) adapter, and a JSON manifest—to the host's extension API.**

The `ayghri/i-have-adhd` open-source project packages a reusable skill for ADHD-friendly AI interactions. To add i-have-adhd support to a new AI assistant platform, you connect the existing rule set to the host's SDK using a lightweight TypeScript adapter and a small manifest file. This keeps the core behavior identical across all runtimes while only the integration layer changes.

## Understand the Three-Part Architecture

The codebase is intentionally split so that the core behavior never changes, while the plumbing remains platform-specific.

### The Rule Set: skills/i-have-adhd/SKILL.md

The canonical behavior lives in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This markdown file defines the ten ADHD-friendly response rules and serves as the single source of truth for every supported runtime. Because the rules are plain markdown with front-matter, any assistant that can read a text file can consume them.

### The Runtime Extension: extensions/i-have-adhd.ts

The generic extension in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) handles four tasks:

- **Load rules** via `loadRules`, stripping any YAML front-matter from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).
- **Persist state** using a custom session-tree entry identified by `STATE_ENTRY_TYPE`.
- **Synchronize context** via `syncContext`, which injects the rule message when the mode is active and withdraws it when disabled.
- **Register UI controls** through `pi.registerCommand("i-have-adhd", …)` for the slash command and `pi.registerFlag("adhd", …)` for the startup flag.

### The Platform Manifests

Each host discovers the skill through a small descriptor file. Existing examples include:

- [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) for Claude Code
- [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) for Codex
- [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) for OpenCode
- [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json) for Qwen

These manifests point the runtime to the `skills/` directory so the extension knows where to find [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).

## Step-by-Step: Add i-have-adhd Support to a New AI Assistant Platform

### 1. Create a Platform-Specific Manifest

Add a JSON file named according to the host's convention, such as [`myplatform-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/myplatform-extension.json). It must declare the skill path so the extension can locate the rules.

```json
{
  "name": "i-have-adhd",
  "version": "0.2.0",
  "description": "ADHD-friendly output for MyPlatform",
  "skills": "./skills/"
}

```

Place this file in the repository root or the host's expected plugin directory.

### 2. Add the Extension Module

Copy [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) to a new file, for example [`extensions/myplatform-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/myplatform-adhd.ts). Keep the core logic identical, but replace the SDK import with your host's API types.

```typescript
// extensions/myplatform-adhd.ts
import { existsSync, readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";

// Replace with your platform's SDK
import {
  getAgentDir,
  type ExtensionAPI,
  type ExtensionContext,
} from "myplatform-sdk";

import {
  contextMessages,
  latestMarkerIsActive,
} from "./context-compat";

const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
const SKILL_PATH = join(EXTENSION_DIR, "..", "skills", "i-have-adhd", "SKILL.md");

// The remainder of the file mirrors extensions/i-have-adhd.ts:
// loadRules, STATE_ENTRY_TYPE, syncContext, registerCommand, registerFlag, etc.

```

The helper functions `contextMessages` and `latestMarkerIsActive` from `./context-compat` remain unchanged because they operate on the conversation tree, not the host SDK.

### 3. Register the Extension with the Host

In the host's plugin entry point, import the adapter and pass the host's extension API to it.

```typescript
import iHaveAdhdExtension from "./extensions/myplatform-adhd.ts";

export default function register(host) {
  iHaveAdhdExtension(host);
}

```

This wires the host's runtime to the skill's loading and synchronization logic.

### 4. Expose the Command and Flag

Ensure the host's UI can trigger `/i-have-adhd` and that users can pass `--adhd` on startup. The existing extension already registers these via `pi.registerCommand("i-have-adhd", …)` and `pi.registerFlag("adhd", …)`. You only need to map those calls to the host's equivalent UI or CLI hooks.

### 5. Test the Integration

Run the repository's test suite after adding a runtime-specific test file.

```bash
python3 -m unittest discover -s tests -v

```

Manually verify that the rule set appears when the mode is enabled and disappears when disabled. Automated tests should confirm that `syncContext` injects and withdraws the rule message correctly.

### 6. Document the Addition

Update [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) or create [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) with host-specific instructions so users know how to enable the skill. Mention the manifest filename, the command syntax, and the startup flag.

## How Context Synchronization Works

Under the hood, the extension uses `syncContext` to keep the conversation in sync with the current mode. When a user invokes `/i-have-adhd` or launches with `--adhd`, the extension:

1. Reads [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) via `loadRules` and strips front-matter.
2. Stores the activation state in the session tree under `STATE_ENTRY_TYPE`.
3. Injects the rule message into `contextMessages` if `latestMarkerIsActive` returns true, or withdraws it when false.

Because the rules are injected dynamically, the assistant's base system prompt remains untouched when the skill is disabled.

## Summary

- The [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) file is the single source of truth for ADHD-friendly rules and never changes per platform.
- [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) provides a generic adapter that loads rules, persists state with `STATE_ENTRY_TYPE`, and synchronizes context via `syncContext`.
- A small manifest file tells the host where the skill lives; examples include [`.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), [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json), and [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json).
- To add i-have-adhd support to a new AI assistant platform, copy the extension, swap the SDK import, create a manifest, and register the `/i-have-adhd` command and `--adhd` flag with the host.
- Optional `hooks/always-on.*` files can enable the skill automatically without manual commands.

## Frequently Asked Questions

### Do I need to edit the ADHD rules for each platform?

No. The ten response rules in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) are platform-agnostic markdown. The extension loads them generically with `loadRules`, so the same file powers Claude Code, Codex, OpenCode, Qwen, and any new runtime.

### What host APIs are required to wire the extension?

The adapter expects an SDK that provides an `ExtensionAPI` and `ExtensionContext`, plus the ability to register a slash command and a Boolean startup flag. The existing [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) calls `pi.registerCommand("i-have-adhd", …)` and `pi.registerFlag("adhd", …)`, which you map to your host's equivalent plugin interface.

### Can the skill be enabled automatically instead of manually?

Yes. The repository includes optional `hooks/always-on.*` files that enable the skill for the entire session without requiring the user to type `/i-have-adhd`. If your platform supports session-level hooks, you can activate the same `syncContext` path at startup.

### How do I verify that my integration works correctly?

Enable the skill and confirm that the rule message from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) appears in the conversation context. Then disable it and ensure the message is withdrawn. The `tests/` directory contains unit tests that validate this behavior; add a runtime-specific test file and run `python3 -m unittest discover -s tests -v` to catch regressions.