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

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, 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, ensuring IDE compatibility while maintaining synchronisation with the canonical rule set.

Runtime Extension: State and Context Management

The 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 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). 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
• 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	Canonical rule set with YAML front-matter
extensions/i-have-adhd.ts	Runtime logic, state management, and context injection
skills/i-have-adhd/agents/openai.yaml	OpenAI platform manifest for skill discovery
.cursor/skills/i-have-adhd/SKILL.md	Cursor IDE mirror of the canonical skill
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:

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

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

Programmatically inject rules within a Pi extension context:

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

Check UI status indicators:

// 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), TypeScript runtime (extensions/i-have-adhd.ts), and YAML manifest (openai.yaml).
• State persistence spans session storage (STATE_ENTRY_TYPE), configuration files (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, 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 checks a hierarchy of persistence mechanisms: session manager entries (STATE_ENTRY_TYPE), the adhd context flag, the 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 that mirrors the canonical skill definition, ensuring the rule set propagates to Cursor's runtime without requiring separate edits.

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