# The Difference Between the Skill File and Extension Implementation in i-have-adhd

> Understand the distinction between the i-have-adhd skill file and its extension implementation. Learn how SKILL.md and extensions/i-have-adhd.ts work together to manage ADHD-friendly responses and session state.

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

---

**The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file is a static Markdown document that declaratively defines ADHD-friendly response rules, while [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) is a TypeScript runtime module that loads those rules, tracks session state, and injects them into the model's conversation context.**

The `ayghri/i-have-adhd` repository splits behavior definition from execution to create an ADHD-friendly coding assistant mode. Understanding the difference between the skill file and the extension implementation in i-have-adhd is essential for anyone customizing or debugging this Pi/OMP extension. The architecture cleanly separates *what* the model should do from *how* that behavior is enforced at runtime.

## The Skill File: Declarative Source of Truth

The **skill file** lives at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and serves as the canonical, human-readable specification for the ADHD-friendly response style. It contains a YAML front-matter block followed by Markdown definitions of the ten rules—such as "Lead with the next action" and "Number multi-step tasks"—that the model must follow. Because it is pure documentation with no executable code, the file is never run directly; it is simply read by the extension at runtime.

A mirror copy also 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) for Cursor compatibility. Neither file tracks state, registers commands, or interacts with the model API.

## The Extension Implementation: Runtime Enforcement Engine

The **extension implementation** in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) is a TypeScript module that executes inside the Pi/OMP runtime to enforce the rules defined in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md). It imports helper utilities from [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts) and interacts with the Pi coding-agent API through `ExtensionAPI` and `ExtensionContext`.

Unlike the static skill file, the extension manages state, registers commands, and programmatically manipulates the conversation context to inject or remove the rules message. It is the engine that makes the skill file's behavior actionable.

## How the Extension Loads and Injects the Skill

The bridge between the two files happens through the `loadRules()` and `syncContext()` functions defined in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts).

### Reading the Skill File at Startup

According to the source code, the extension reads and caches the Markdown text at startup using `loadRules()` on lines 46–64. This function reads `SKILL_PATH` via `readFileSync` and strips the YAML front-matter with `stripFrontmatter()` before caching the text for later use.

```ts
// extensions/i-have-adhd.ts – load the skill text
function loadRules(): string {
  const content = readFileSync(SKILL_PATH, "utf8");
  return stripFrontmatter(content);
}

```

### Injecting Rules into the Conversation Context

When ADHD mode is enabled, `syncContext()` (lines 18–43) checks whether the rules have already been injected into the session. If they have not, it sends a hidden custom message via `pi.sendMessage` on lines 22–28. The `display: false` flag ensures the user does not see the full rules text in the chat interface, while `triggerTurn: false` prevents the message from triggering a model response on its own.

```ts
// extensions/i-have-adhd.ts – sync rules into the conversation
if (enabled && !injected) {
  pi.sendMessage(
    {
      customType: RULES_MESSAGE_TYPE,
      content: `${RULES_HEADER}\n\n${rules}`,
      display: false,
    },
    { triggerTurn: false },
  );
}

```

When the mode is disabled, the extension sends a "disabled" notice instead, keeping the context synchronized with the user's current preference.

## State Management and User Commands

State management is entirely handled by the extension implementation, not the skill file. The extension defines `STATE_ENTRY_TYPE` and `AdhdModeState` to persist the enable/disable flag across sessions through `getSavedState` and `setEnabled`.

Users interact with the system through the `/i-have-adhd` command, the `/skill:i-have-adhd` alias, or natural-language phrases such as "stop adhd mode." When active, the extension updates a UI status badge labeled `ADHD ON` and notifies the user of the current state. The extension also respects an `adhd` launch flag and an "always-on" configuration file to automatically enable the mode when appropriate.

## Summary

- **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** is a static Markdown file that defines the ten ADHD-friendly rules declaratively; it contains no executable logic.
- **[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)** is the TypeScript runtime engine that reads the skill file, tracks session state, and injects or removes the rules from the model context.
- The `loadRules()` function (lines 46–64) strips the skill file's front-matter and caches the text for injection.
- The `syncContext()` function (lines 18–43) and `pi.sendMessage` (lines 22–28) push the rules into the conversation as a hidden custom message when ADHD mode is enabled.
- All state persistence, command registration, and UI badge updates are handled exclusively by the extension implementation.

## Frequently Asked Questions

### What is the exact role of the skill file in i-have-adhd?

The skill file acts as the single source of truth for the ADHD-friendly behavior specification. It is pure documentation that defines rules like leading with the next actionable step and numbering multi-step tasks, but it has no state management or execution logic.

### How does the extension implementation read the skill file?

At startup, the extension calls `loadRules()` in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), which uses `readFileSync` to read [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and then calls `stripFrontmatter()` to remove the YAML header before caching the remaining Markdown text.

### Can the skill file work without the extension implementation?

No. The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file is never executed on its own. Without the extension implementation in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), there is no mechanism to load the rules, track the ADHD mode state, or inject the instructions into the model's conversation context.

### Where is the ADHD mode state stored?

The extension stores the mode state in the Pi/OMP session state using `AdhdModeState` and `STATE_ENTRY_TYPE`. It persists across sessions through `getSavedState` and `setEnabled`, and it controls whether `syncContext()` injects or removes the rules message.