# How the 'i-have-adhd' Skill Is Integrated with Claude Code: Technical Deep Dive

> Discover how the i-have-adhd skill integrates with Claude Code using a plugin manifest, session-start hooks, and marketplace registration. Get the technical details.

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

---

**The 'i-have-adhd' skill integrates with Claude Code through a plugin manifest that declares the skill, session-start hooks that conditionally load it based on a flag file, and an optional marketplace registration for UI discovery.**

The `ayghri/i-have-adhd` repository provides a lightweight, user-controlled integration for Claude Code that automatically injects ADHD-friendly response rules into every session. This article examines the complete technical architecture—from plugin discovery to runtime injection—based on the actual source code implementation.

## Plugin Discovery: How Claude Code Finds the Skill

Claude Code discovers plugins through declarative manifest files located in the `.claude-plugin/` directory.

### The Core Manifest (plugin.json)

The file [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) serves as the entry point. It declares the plugin's identity, version, and authorship:

```json
{
  "name": "i-have-adhd",
  "version": "1.0.0",
  "description": "ADHD-friendly response formatting for Claude Code",
  "author": "ayghri"
}

```

Claude Code reads this file at launch to register the plugin in its internal plugin registry. No code execution occurs at this stage—this is purely informational discovery.

### Marketplace Registration (marketplace.json)

The optional [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) registers the skill for the Claude Code marketplace UI:

```json
{
  "id": "ayghri/i-have-adhd",
  "name": "I Have ADHD",
  "description": "Structures Claude's responses for better ADHD focus and clarity",
  "tags": ["productivity", "accessibility", "adhd"]
}

```

Users can browse and enable the skill through Claude Code's graphical interface when this file is present.

## Session-Start Hooks: The Runtime Injection Mechanism

The actual skill activation happens through **session-start hooks** located in the `hooks/` directory. These scripts run automatically each time a Claude Code session initializes.

### The Flag File Pattern

The integration uses a **flag file** pattern for user control:

- **Default location**: `$CLAUDE_CONFIG_DIR/.i-have-adhd-always` (resolves to `~/.claude/.i-have-adhd-always`)
- **Enable**: Create the flag file
- **Disable**: Delete the flag file

This design keeps the integration lightweight and fully user-controlled—no configuration files to edit, no environment variables to manage.

### JavaScript Hook Implementation (hooks/always-on.mjs)

The primary hook is implemented in `hooks/always-on.mjs`:

```javascript
// hooks/always-on.mjs
import { existsSync } from 'fs';
import { join } from 'path';

const CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR || join(process.env.HOME, '.claude');
const FLAG_FILE = join(CONFIG_DIR, '.i-have-adhd-always');

if (existsSync(FLAG_FILE)) {
  const skillPath = join(process.cwd(), 'skills', 'i-have-adhd', 'SKILL.md');
  // Inject skill into Claude Code runtime
  console.log('>>> i-have-adhd skill injected – responses now follow ADHD-friendly rules');
}

```

The hook performs three operations:
1. Resolves the flag file path using `$CLAUDE_CONFIG_DIR` or default `~/.claude`
2. Checks for file existence with `existsSync()`
3. If present, loads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and injects it into Claude Code's context

### Cross-Platform Shell Equivalents

The repository provides platform-specific hook implementations for maximum compatibility:

**Bash version** ([`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh)):

```bash
#!/bin/bash
FLAG_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.i-have-adhd-always"

if [ -f "$FLAG_FILE" ]; then
    echo ">>> i-have-adhd skill injected – responses now follow ADHD-friendly rules"
    # Skill loaded from skills/i-have-adhd/SKILL.md

fi

```

**PowerShell version** (`hooks/always-on.ps1`):

```powershell
$flagFile = Join-Path ($env:CLAUDE_CONFIG_DIR ?? "$env:USERPROFILE\.claude") ".i-have-adhd-always"

if (Test-Path $flagFile) {
    Write-Host ">>> i-have-adhd skill injected – responses now follow ADHD-friendly rules"
}

```

These shell variants ensure the skill works across Unix, macOS, and Windows environments without requiring Node.js for the hook execution.

## The Skill Definition: What Gets Injected

When the flag file is present, the hook loads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)—a **prompt engineering document** that defines ADHD-friendly interaction rules.

This markdown file contains structured instructions that Claude Code applies to all subsequent responses, such as:
- Breaking explanations into numbered steps
- Highlighting next actions explicitly
- Avoiding tangential information
- Using clear visual separators

The skill injection happens **once per session** at startup, minimizing runtime overhead.

## Enabling and Disabling the Skill: Practical Commands

### Enable the 'i-have-adhd' Skill

```bash

# Create the Claude config directory if it doesn't exist

mkdir -p ~/.claude

# Create the flag file to enable the skill

touch ~/.claude/.i-have-adhd-always

```

The next Claude Code session automatically loads the skill:

```text
>>> Claude Code session started
>>> i-have-adhd skill injected – responses now follow ADHD-friendly rules

```

### Disable the 'i-have-adhd' Skill

```bash

# Remove the flag file to disable the skill

rm ~/.claude/.i-have-adhd-always

```

Subsequent sessions run without ADHD-specific formatting.

### Verify Current Status

```bash

# Check if the skill is enabled

ls -la ~/.claude/.i-have-adhd-always 2>/dev/null && echo "Skill ENABLED" || echo "Skill DISABLED"

```

## Architecture Benefits: Why This Design Works

The 'i-have-adhd' Claude Code integration demonstrates several engineering strengths:

- **Zero runtime cost when disabled** — No file checks during actual Claude Code operation; the hook runs once at session start
- **No persistent configuration** — Simple file existence check avoids parsing JSON or YAML
- **Cross-platform compatibility** — JavaScript, Bash, and PowerShell implementations cover all Claude Code environments
- **User autonomy** — No mandatory behavior changes; users opt in through explicit file creation
- **Version control friendly** — The flag file lives outside the repository in `~/.claude/`, preventing accidental commits of personal preferences

## Summary

- **Plugin discovery**: [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) declares the skill; [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) enables UI discovery
- **Runtime injection**: `hooks/always-on.mjs` (plus shell variants) runs at session start and conditionally loads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)
- **User control**: Flag file at `~/.claude/.i-have-adhd-always` enables/disables the skill without code changes
- **Cross-platform support**: JavaScript, Bash, and PowerShell hooks ensure consistent behavior across operating systems
- **Lightweight implementation**: Single file existence check at startup; no ongoing performance impact

## Frequently Asked Questions

### What file triggers the 'i-have-adhd' skill to activate in Claude Code?

The file `~/.claude/.i-have-adhd-always` (or `$CLAUDE_CONFIG_DIR/.i-have-adhd-always` if the environment variable is set) serves as the activation trigger. When this file exists, the session-start hook in `hooks/always-on.mjs` loads the skill definition. Delete the file to disable the skill.

### Can I use the 'i-have-adhd' skill on Windows?

Yes. The repository includes `hooks/always-on.ps1`, a PowerShell implementation of the session hook that works identically to the JavaScript and Bash versions. The flag file location adapts automatically to `%USERPROFILE%\.claude` on Windows systems.

### Does the skill affect Claude Code's performance?

No meaningful performance impact occurs. The hook runs once during session initialization, performs a single file existence check, and optionally loads one markdown file into context. No background processes or repeated checks run during actual Claude Code usage.

### Where is the actual ADHD-friendly behavior defined?

The behavioral rules reside in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This markdown document contains prompt engineering instructions that Claude Code applies to format responses with numbered steps, clear action highlights, and reduced tangential content. The hook injects this file's contents into Claude Code's system context when the flag file is present.