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

The ayghri/i-have-adhd repository treats 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 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. 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 registers the skill by pointing to the canonical path:

{
  "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 and .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. 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.

Contribution Workflow Enforcement

The 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, 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 demonstrates this pattern:

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:

# 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. This CI workflow executes automated comparisons between skills/i-have-adhd/SKILL.md and .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 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 manifests.
• A mirror at .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 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 performs a diff check between skills/i-have-adhd/SKILL.md and .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 manifest that declares "name": "i-have-adhd" and points the "skill" field to skills/i-have-adhd/SKILL.md. The runtime then implements a loader similar to the TypeScript example in 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 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 in the repository root. Users can also inspect the Cursor-compatible mirror at .cursor/skills/i-have-adhd/SKILL.md, which must contain identical content according to the project's AGENTS.md contribution guidelines.

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