# How the i-have-adhd Skill Is Organized: A Technical Deep Dive

> Explore the technical deep dive of the i-have-adhd skill's organization. Learn how markdown rules, TypeScript extensions, and agent manifests enable ADHD-friendly formatting via dynamic context synchronization.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-28

---

**The i-have-adhd skill is organized into three distinct layers—a markdown rule definition, a TypeScript runtime extension, and an agent manifest—that work together to inject ADHD-friendly formatting rules into model responses through dynamic context synchronization.**

The ayghri/i-have-adhd repository implements a modular architecture that separates declarative content from runtime logic. Understanding how the i-have-adhd skill is organized reveals a system designed for maintainability, with clear boundaries between rule storage, state management, and platform integration.

## The Three-Layer Architecture

The skill divides responsibilities across three core components, each stored in specific paths within the repository.

### Skill Definition: The Rule Set

At the heart of the system lies **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)**, a markdown document that stores the human-readable rule set and metadata. This file contains:

- YAML front-matter with configuration metadata
- The "pre-send" checklist that shapes ADHD-friendly output
- Declarative rules applied to every model response when active

A Cursor-compatible mirror exists at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md), ensuring IDE compatibility while maintaining synchronisation with the canonical rule set.

### Runtime Extension: State and Context Management

The **[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)** module handles all dynamic functionality. Implemented in TypeScript, this extension:

- Reads the rule file via `loadRules()` and processes it through `stripFrontmatter()` to cache raw rule text
- Manages a persistent **enabled** flag across sessions using `STATE_ENTRY_TYPE`
- Registers the `/i-have-adhd` command (supporting on/off/toggle) via `pi.registerCommand`
- Synchronizes rules with the model's context through `syncContext()`, sending hidden **RULES_MESSAGE_TYPE** messages when enabled and **DISABLED_MESSAGE_TYPE** when turned off
- Updates UI badges unless suppressed by `config.hideStatus`

### Agent Manifest: Platform Discovery

The **[`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml)** file serves as the discovery mechanism for the OpenAI runtime. This YAML manifest declares the display name, description, and default prompts that instruct the model to invoke the skill.

## Runtime Integration Flow

The TypeScript extension orchestrates the skill's behavior through a specific execution sequence.

### Loading and Parsing Rules

When initialised, the extension calls `loadRules()` to read `SKILL_PATH` ([`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)). The helper function `stripFrontmatter()` removes YAML metadata, leaving only the actionable rule text for context injection.

### State Persistence

The `restoreState()` function checks multiple sources to determine the initial enabled status:

- Session manager entries (`STATE_ENTRY_TYPE`)
- The `adhd` flag in conversation context
- Configuration file [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json)
- Presence of `.i-have-adhd-always` marker file

### Context Synchronization

The `syncContext()` method inspects the conversation history using `latestMarkerIsActive`. If enabled and rules are not present, it injects a hidden system message containing `RULES_HEADER` plus the rule text using `RULES_MESSAGE_TYPE`. When disabled, it sends `DISABLED_MESSAGE_TYPE` to remove the constraints.

### Command Registration and Input Handling

The extension registers the `/i-have-adhd` command with subcommands for explicit on/off control. An input hook also listens for:

- `/skill:i-have-adhd` invocations
- Stop phrases: `"stop adhd mode"` and `"normal mode"`

When stop phrases are detected, the skill automatically disables and returns `DISABLE_CONFIRMATION` ("ADHD mode disabled.").

## Project File Structure

| File | Purpose |
|------|---------|
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Canonical rule set with YAML front-matter |
| [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) | Runtime logic, state management, and context injection |
| [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) | OpenAI platform manifest for skill discovery |
| [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) | Cursor IDE mirror of the canonical skill |
| [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json) | Optional JSON configuration (`alwaysOn`, `hideStatus`) |
| `.i-have-adhd-always` | Optional marker file forcing session-wide activation |

## Usage Examples

Toggle the skill interactively through chat commands:

```text
/i-have-adhd          → toggles on/off
/i-have-adhd on       → forces the mode on
/i-have-adhd off      → forces the mode off

```

Disable via natural language:

```text
stop adhd mode        → automatically turns the mode off and replies
                      → "ADHD mode disabled."

```

Programmatically inject rules within a Pi extension context:

```typescript
// Assume `pi` is the ExtensionAPI instance
pi.sendMessage(
  { customType: "i-have-adhd-rules", content: "…rules…" },
  { triggerTurn: false }
);

```

Check UI status indicators:

```typescript
// The UI displays a green dot followed by "ADHD ON" when active
ctx.ui.setStatus("i-have-adhd", "● ADHD ON");

```

## Summary

- The i-have-adhd skill organization relies on three layers: markdown rules ([`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)), TypeScript runtime ([`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)), and YAML manifest ([`openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/openai.yaml)).
- State persistence spans session storage (`STATE_ENTRY_TYPE`), configuration files ([`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json)), and marker files (`.i-have-adhd-always`).
- Rule injection uses hidden message types (`RULES_MESSAGE_TYPE`) to dynamically modify model context without visible chat interference.
- The system supports multiple activation methods: slash commands (`/i-have-adhd`), natural language stop phrases, and programmatic API calls.
- A mirrored skill file ensures compatibility with Cursor IDE while maintaining a single source of truth.

## Frequently Asked Questions

### Where are the ADHD formatting rules stored?

The rules live in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), a markdown file containing YAML front-matter and the pre-send checklist. The extension loads this file at runtime, strips the front-matter using `stripFrontmatter()`, and caches the text for context injection.

### How does the skill maintain its enabled state between sessions?

The `restoreState()` function in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) checks a hierarchy of persistence mechanisms: session manager entries (`STATE_ENTRY_TYPE`), the `adhd` context flag, the [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json) config file, and the presence of a `.i-have-adhd-always` marker file in the workspace.

### What happens when I type "stop adhd mode"?

The extension's input hook detects stop phrases including `"stop adhd mode"` and `"normal mode"`, automatically setting the enabled flag to false and sending a `DISABLED_MESSAGE_TYPE` context message. The system returns the fixed confirmation string: "ADHD mode disabled."

### Can I use this skill with the Cursor IDE?

Yes. The repository maintains a synchronized copy at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) that mirrors the canonical skill definition, ensuring the rule set propagates to Cursor's runtime without requiring separate edits.