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

The SKILL.md file is a static Markdown document that declaratively defines ADHD-friendly response rules, while 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 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 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 is a TypeScript module that executes inside the Pi/OMP runtime to enforce the rules defined in SKILL.md. It imports helper utilities from 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.

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.

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

// 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 is a static Markdown file that defines the ten ADHD-friendly rules declaratively; it contains no executable logic.
• 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, which uses readFileSync to read 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 file is never executed on its own. Without the extension implementation in 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.

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