# i‑have‑adhd Skill Integration Patterns: 3 Ways to Add Custom Rules for Developers

> Developers can extend i-have-adhd skill with custom rules using fork-and-edit rule sets, runtime manifests, or hook-based extensions. Add your own logic without compiled code.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Developers can extend the i‑have‑adhd skill through three integration patterns: fork‑and‑edit rule sets, runtime‑specific manifests, and hook‑based extensions—all without compiled code.**

The `ayghri/i‑have‑adhd` repository is a portable AI skill plugin designed for multiple runtimes including Claude, Codex, Pi, OMP, OpenCode, Qwen, Kimi, and Gemini. Because the core logic lives entirely in a Markdown‑based rule set, developers can implement custom integration patterns to modify behavior without touching compiled code. This article explains each pattern with exact file paths and working examples from the source.

---

## Fork‑and‑Edit Rule Set Pattern

The simplest integration pattern for adding custom rules is to fork the repository and modify the canonical rule file directly.

The skill's rule engine reads from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) in pure Markdown format. This file exists in two locations for runtime compatibility:

- [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) — canonical source
- [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) — mirror for Cursor‑compatible runtimes

Both files must stay synchronized if you support Cursor‑based tools.

### Adding a Custom Rule

Rules follow a structured Markdown format with numbered sections. Here's how to insert a new rule:

```markdown

## Custom Rule: Highlight Important Steps

### 11. Emphasize critical actions

When a step is a "must‑do", prepend it with **⚡** and add a short justification.

⚡ 1. Run `npm install super‑fast‑lib` – required for performance.

```

The rule engine parses these sections automatically. No recompilation or build step is required—runtimes pick up changes on plugin reload.

---

## Runtime‑Specific Manifest Pattern

Each supported runtime loads the skill through its own manifest file. By modifying the appropriate manifest, you can redirect any runtime to a custom fork or local copy of the rule set.

### Manifest Files by Runtime

| Runtime | Manifest File | Purpose |
|---------|---------------|---------|
| Claude | [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) | Claude Code plugin definition |
| Codex | [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) | OpenAI Codex integration |
| Pi / OMP | [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) | npm‑based runtime entry |
| OpenCode | [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) | OpenCode extension manifest |
| Qwen | [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json) | Qwen runtime loader |
| Kimi | [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json) | Kimi plugin configuration |
| Gemini | [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) | Gemini extension manifest |

### Redirecting Claude to Your Fork

Edit [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) to point at your custom repository:

```json
{
  "name": "i-have-adhd",
  "description": "ADHD‑friendly output plugin",
  "source": "https://github.com/your-username/i-have-adhd",
  "entry": "skills/i-have-adhd/SKILL.md"
}

```

The `source` field tells Claude where to fetch updates. The `entry` field specifies the path to your modified [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) within that repository.

---

## Hook‑Based Extension Pattern

For developers needing programmatic control, the repository provides a generic hook system defined in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) with implementations in `hooks/always-on.mjs`.

This pattern lets you inject custom code before or after skill invocation—useful for validation, logging, metrics, or dynamic rule preprocessing.

### Hook Configuration Structure

The [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) file registers which hooks are active and their execution order. The `always-on.mjs` module exports handler functions that the runtime calls at specific lifecycle points.

### Example: Logging Rule Loads

Create a logging hook in `hooks/always-on.mjs`:

```javascript
// hooks/always-on.mjs
export async function onSkillLoad(context) {
  console.log('i-have-adhd skill loaded at', new Date().toISOString());
  // Add custom metrics, telemetry, or validation here
  return context;
}

```

The `context` object contains the parsed rule set and runtime environment. Your hook can modify `context.rules` before returning, enabling dynamic rule injection based on external conditions.

---

## Complete Workflow: Adding Custom Rules

Follow this sequence to implement any of the three integration patterns:

1. **Fork the repository**

   ```bash
   git clone https://github.com/your-username/i-have-adhd.git
   ```

2. **Modify [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)**

   Add your custom rules under the `## Rules` section, following the existing numbered format.

3. **Update the relevant manifest**

   - For Claude: edit [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) `source` field
   - For Pi/OMP: bump version in [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) and update entry points
   - For other runtimes: modify their respective JSON manifests

4. **Publish the plugin**

   Use the appropriate CLI for your target runtime:
   
   ```bash
   claude plugin marketplace add your-username/i-have-adhd
   ```

5. **Restart the runtime**

   Changes take effect on next plugin load—no build step required.

---

## Summary

- **Fork‑and‑edit** is the fastest path for rule changes—edit [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) directly.
- **Runtime manifests** control which rule source each runtime consumes—modify files like [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) or [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json).
- **Hook extensions** enable programmatic logic through [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) and `hooks/always-on.mjs` for validation, logging, or preprocessing.
- All patterns use the same underlying Markdown rule engine, so custom rules work across every supported runtime without platform‑specific code.

---

## Frequently Asked Questions

### Can I use multiple integration patterns together?

Yes. You can fork the repository, modify [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), redirect runtimes through manifest files, *and* add hooks for logging or validation. The patterns are composable—hooks execute regardless of which rule source the manifest points to.

### Do I need to rebuild or compile anything when adding custom rules?

No. The i‑have‑adhd skill uses pure Markdown for its rule set. Runtimes parse [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) at load time, so changes take effect immediately after restarting the runtime or reloading the plugin.

### Will my custom rules work across all supported AI runtimes?

Yes, provided you maintain synchronization between [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and its Cursor mirror at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md). The rule engine is identical across Claude, Codex, Pi, OMP, OpenCode, Qwen, Kimi, and Gemini—only the manifest loader differs.

### How do I debug hook execution failures?

Add error handling in `hooks/always-on.mjs` and log to `stderr`. The hook system in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) supports an optional `debug` flag that emits verbose lifecycle events. Check your runtime's plugin logs for `onSkillLoad` and `onSkillInvoke` tracing.