Why SKILL.md Comes First Before the .cursor Mirror in Source-of-Truth Rules

The canonical 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, 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 (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 exists solely to satisfy the Cursor runtime contract, which expects skill definitions at that specific path. As documented in 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. 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 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 mandates a disciplined editing sequence to preserve consistency.

First, edit the canonical skill file to modify rule behavior:

# Edit the authoritative source

vim skills/i-have-adhd/SKILL.md

Next, synchronize the Cursor mirror to match:

# 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:

# 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 is the sole authoritative source for ADHD-friendly response rules as defined in 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 violate the source-of-truth policy outlined in 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 directly or through abstraction layers. Only the Cursor runtime requires the specific path .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.

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