# How SKILL.md Serves as the Canonical Specification in the i-have-adhd Repository

> Discover how SKILL.md acts as the canonical specification for the i-have-adhd repository. Learn how AI runtimes use this single source of truth for ADHD-friendly assistant behavior.

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

---

**The ayghri/i-have-adhd repository treats [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) as the single source of truth that defines ADHD-friendly assistant behavior, which multiple AI runtimes consume directly while a CI-enforced mirror maintains Cursor compatibility.**

The open-source project ayghri/i-have-adhd centralizes its behavioral logic in a Markdown specification file rather than scattering rules across runtime-specific implementations. By treating [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) as the canonical specification, the repository ensures that OpenCode, Claude, Codex, Gemini, and other adapters apply identical formatting rules without code duplication.

## The Canonical Specification Architecture

### Primary Definition Location

The canonical file resides at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This file contains the complete rule set that shapes assistant output for readers with ADHD, serving as the authoritative reference that all runtimes must follow. Rather than embedding logic in adapter-specific code, each runtime reads this single document to determine formatting constraints, response structures, and stylistic requirements.

### Runtime Contract Design

Each plugin manifest declares the skill name `i-have-adhd` and references the specification file directly. For example, [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) registers the skill by pointing to the canonical path:

```json
{
  "name": "i-have-adhd",
  "description": "ADHD‑friendly output style",
  "entry": "./.opencode/plugins/i-have-adhd.mjs",
  "skill": "skills/i-have-adhd/SKILL.md"
}

```

Similarly, [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) maintain parallel declarations, allowing diverse runtimes to locate and load the same behavioral rules from the canonical specification.

## Mirror Synchronization Strategy

### Cursor Compatibility Layer

To support Cursor-specific workflows, the repository maintains an identical copy at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md). This mirror location follows Cursor's convention for hidden configuration directories while preserving byte-for-byte parity with the canonical version in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md).

### Contribution Workflow Enforcement

The [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) file documents the strict requirement that any modification to the canonical specification must propagate to the Cursor mirror. This design creates a unidirectional flow: developers edit the canonical [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), and automated processes ensure the `.cursor` mirror remains synchronized, preventing drift between editor environments.

## Runtime Loading and Execution

### Dynamic Skill Registration

At runtime, adapters load the specification using runtime-specific APIs. The TypeScript implementation in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) demonstrates this pattern:

```typescript
import { loadSkill } from '@opencode/runtime';
const skillSpec = await loadSkill('skills/i-have-adhd/SKILL.md');
runtime.registerSkill('i-have-adhd', skillSpec);

```

This approach decouples the behavioral specification from runtime implementation, allowing the `loadSkill` function to parse the Markdown rules and apply them through `registerSkill`.

### User Invocation Interface

End users activate the skill through a simple chat command:

```yaml

# Invoke ADHD-friendly formatting

/i-have-adhd

# Disable the mode

stop adhd mode

```

Once invoked, the assistant references the loaded specification to structure responses according to the rules defined in the canonical file.

## CI Enforcement and Drift Prevention

The repository prevents specification divergence through [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml). This CI workflow executes automated comparisons between [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md), failing builds if the files differ. This enforcement guarantees that the Cursor mirror never falls out of sync with the canonical definition, eliminating the risk of behavioral inconsistencies across editor environments.

## Summary

- The canonical specification lives at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and defines all ADHD-friendly formatting rules in one location.
- Runtime adapters like OpenCode and Claude consume this file directly through their respective [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) manifests.
- A 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) provides Cursor-specific compatibility while maintaining identical content.
- The CI workflow in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) enforces byte-for-byte parity between the canonical file and its mirror.
- Dynamic loading via `loadSkill()` and `registerSkill()` allows runtimes to apply the specification without embedding rules in adapter code.

## Frequently Asked Questions

### What happens if the canonical SKILL.md and the Cursor mirror get out of sync?

The CI pipeline immediately fails, blocking merges until the files match. The workflow defined in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) performs a diff check between [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md), ensuring developers cannot accidentally merge divergent specifications.

### How do new runtimes add support for the i-have-adhd skill?

New adapters create a [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) manifest that declares `"name": "i-have-adhd"` and points the `"skill"` field to [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). The runtime then implements a loader similar to the TypeScript example in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), calling `loadSkill()` to parse the Markdown rules and `registerSkill()` to activate them.

### Why use a Markdown file instead of code for the specification?

Markdown provides a human-readable, version-controllable format that non-developers can edit while remaining machine-parseable. This choice centralizes behavioral logic in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) so that rule updates require editing only one file, with changes automatically propagating to all consuming runtimes including OpenCode, Claude, and Cursor.

### Where is the skill specification located for manual inspection?

The canonical file resides at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) in the repository root. Users can also inspect the Cursor-compatible 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), which must contain identical content according to the project's [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) contribution guidelines.