# Why SKILL.md Comes First Before the .cursor Mirror in Source-of-Truth Rules > Understand why SKILL.md is the primary source of truth for ADHD response rules, not the .cursor mirror. Learn about synchronization and best practices. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: internals - Published: 2026-09-10 --- **The canonical [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) serves as the authoritative source of truth for the 10 ADHD-friendly response rules, while the `.cursor` version functions solely as a runtime-specific mirror that must be synchronized after every change to the primary file.** The `ayghri/i-have-adhd` repository maintains a strict file hierarchy to ensure consistent agent behavior across multiple AI platforms. Understanding why **SKILL.md comes first** in the source-of-truth rules is essential for contributors working with ADHD-friendly response formatting. This architecture prevents configuration drift and simplifies maintenance across Claude, Codex, Cursor, and other supported runtimes. ## The Canonical Definition vs. the Cursor Mirror The repository distinguishes between authoritative rule definitions and runtime compatibility layers. ### skills/i-have-adhd/SKILL.md (The Source of Truth) Located at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), this file holds the **definitive set of 10 rules** that govern how agents structure responses for readers with ADHD. According to the Agent guide in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) (lines 27-30), this path is explicitly designated as *"The source of truth for the 10 ADHD-friendly response rules."* All logic modifications must originate here to maintain consistency across every supported platform. ### .cursor/skills/i-have-adhd/SKILL.md (The Runtime Mirror) The duplicate located at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) exists solely to satisfy the **Cursor runtime** contract, which expects skill definitions at that specific path. As documented in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) (lines 53-56), this copy is **not** authoritative. Instead, it functions as a mirror that must remain byte-for-byte identical to the canonical version. Divergence between these files creates undefined behavior for Cursor users while violating the repository's source-of-truth policy. ## Why SKILL.md Takes Precedence in the Source-of-Truth Rules Establishing a clear hierarchy between these files addresses three critical engineering requirements. **Single source of truth** – Centralizing the rule definition in one canonical file eliminates the risk of divergent implementations. While runtimes like Claude, Codex, Pi, OMP, and OpenCode reference different manifest locations (`.claude-plugin/`, `.codex-plugin/`, `extensions/`, etc.), they all ultimately derive their ADHD-friendly formatting logic from the primary [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md). This guarantees identical behavior regardless of which AI agent processes the request. **Ease of maintenance** – Developers modify only the canonical file during updates. The `.cursor` mirror then receives changes via automated synchronization or a simple copy operation. This workflow eliminates the cognitive overhead of remembering to update multiple files and prevents the common failure mode where one copy is updated while another remains stale. **Runtime contracts** – Each platform maintains its own directory structure for plugin manifests, but these are implementation details. The canonical [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) abstracts the business logic away from these platform-specific paths, allowing the repository to support new runtimes without duplicating rule definitions. ## Enforced Workflow for Synchronizing Changes The **Source-of-truth rules** section in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) mandates a disciplined editing sequence to preserve consistency. First, edit the canonical skill file to modify rule behavior: ```bash # Edit the authoritative source vim skills/i-have-adhd/SKILL.md ``` Next, synchronize the Cursor mirror to match: ```bash # Copy changes to the runtime-specific location cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md ``` Finally, verify byte-for-byte equality: ```bash # Diff should return no output if properly synced diff -u skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md ``` This edit-then-sync pattern ensures that the `.cursor` mirror never contains logic that diverges from the canonical definition. ## Summary - **Canonical precedence**: [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) is the sole authoritative source for ADHD-friendly response rules as defined in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md). - **Mirror purpose**: The `.cursor` copy exists only for Cursor runtime compatibility and must never be edited directly. - **Synchronization requirement**: All changes must flow from the canonical file to the mirror, never the reverse. - **Consistency guarantee**: This hierarchy prevents drift across Claude, Codex, Cursor, and other supported AI platforms. ## Frequently Asked Questions ### What happens if I edit the .cursor mirror directly? Direct modifications to [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) violate the source-of-truth policy outlined in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md). While the Cursor runtime would temporarily use your changes, the next synchronization from the canonical file would overwrite them, causing lost work and potential confusion for other runtime users. ### Which runtimes use the canonical SKILL.md versus the .cursor mirror? Runtime-agnostic manifests (Claude, Codex, Pi, OMP, OpenCode) reference the canonical [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) directly or through abstraction layers. Only the Cursor runtime requires the specific path [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md), making it the sole consumer of the mirror file. ### How do I verify the files are synchronized? Run `diff -u skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md` after making changes. An empty output confirms synchronization, while any differences indicate the mirror is outdated and requires updating via `cp`. ### Can the synchronization between SKILL.md and the .cursor mirror be automated? Yes. The repository structure supports automated copying via CI/CD pipelines or git hooks. Since the canonical file always leads, any automation should trigger `cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md` whenever the primary file changes, ensuring the mirror never falls out of sync.