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

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 rule set, the 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. 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 handles four tasks:

• Load rules via loadRules, stripping any YAML front-matter from 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 for Claude Code
• .codex-plugin/plugin.json for Codex
• opencode.json for OpenCode
• qwen-extension.json for Qwen

These manifests point the runtime to the skills/ directory so the extension knows where to find 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. It must declare the skill path so the extension can locate the rules.

{
  "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 to a new file, for example extensions/myplatform-adhd.ts. Keep the core logic identical, but replace the SDK import with your host's API types.

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

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.

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 or create 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 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 file is the single source of truth for ADHD-friendly rules and never changes per platform.
• 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, .codex-plugin/plugin.json, opencode.json, and 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 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 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 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.

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