# SKILL.md and Its .cursor Mirror File: Purpose and Differences in the i-have-adhd Repository > Understand SKILL.md's purpose as the source of truth and its .cursor mirror file for Cursor IDE compatibility. Learn their key differences in the i-have-adhd repository. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: deep-dive - Published: 2026-09-13 --- **The canonical [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) acts as the single source of truth for runtime behavior, while the `.cursor` mirror file exists solely for Cursor IDE compatibility and does not influence execution.** The `ayghri/i-have-adhd` repository defines an ADHD-friendly agent skill using a dual-file structure to support both runtime agents and developer tooling. Understanding the relationship between the primary **SKILL.md and its .cursor mirror file** is essential for contributors who modify the skill's response rules, metadata, or the `disable-model-invocation` flag. ## What Is the Canonical SKILL.md File? The authoritative definition 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 canonical metadata, the 10 ADHD-friendly response rules, and the `disable-model-invocation` flag that all runtimes read when loading the agent. When you invoke the skill using `/invoke i-have-adhd`, the harness specifically reads from this path to configure the agent's behavior. According to the source code structure documented in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md), this location serves as the **single source of truth** for the skill's operational logic. ## What Is the .cursor Mirror File? The repository ships a duplicate 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 file is **not** used by any runtime or agent harness. Instead, it exists solely to satisfy the [Cursor](https://cursor.com) IDE's expectation of finding a skill manifest at that specific hidden-directory location. As noted in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) under the *Skill-mirror* description, this copy is strictly for developer tooling convenience. ## Key Differences Between the Canonical and Mirror Files The two files serve entirely different purposes despite containing identical content: - **Canonical File ([`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md))**: Drives runtime behavior. Contains the authoritative rules, metadata, and configuration flags that the agent harness parses during invocation. - **Cursor Mirror ([`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md))**: Provides IDE compatibility. Exists only for the Cursor editor's internal skill discovery and contributes nothing to execution. ## How to Synchronize the Files Per [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md), any modification to the canonical [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) must be mirrored to the `.cursor` directory to maintain consistency. Use the following workflow after editing the primary file: ```bash # From the repository root cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md # Verify the copy is identical cmp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md ``` After committing your changes to the canonical file, always include the synchronization step in your commit workflow: ```bash # After editing the canonical file git add skills/i-have-adhd/SKILL.md git commit -m "Update ADHD skill rules" # Keep the mirror in sync cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md ``` ## Where Runtimes Load the Skill When invoking the skill within a compatible runtime (e.g., Claude Code), the system explicitly targets the canonical path: ```text /invoke i-have-adhd # The harness reads skills/i-have-adhd/SKILL.md, ignoring the .cursor directory entirely ``` The runtime does not check the `.cursor` path for skill definitions, making the mirror file invisible to actual agent execution. ## Summary - The **canonical [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)** at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) contains the authoritative rules and metadata used by all runtimes. - The **`.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) exists only for Cursor IDE compatibility and does not affect agent behavior. - Contributors must keep the files synchronized using `cp` and verify with `cmp` as outlined in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md). - The runtime loads exclusively from the `skills/` directory, ignoring the `.cursor` mirror during invocation. ## Frequently Asked Questions ### Which file does the runtime actually use? The runtime uses the canonical file at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). The agent harness reads this specific path to load the 10 ADHD-friendly response rules and the `disable-model-invocation` flag. The `.cursor` mirror is never accessed during execution. ### Do I need to manually update the .cursor mirror after editing SKILL.md? Yes. According to [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md), you must manually copy the canonical file to the mirror location using `cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md`. Always verify the copy succeeded with `cmp` before submitting your changes. ### What happens if the canonical and mirror files are out of sync? The runtime continues to function correctly using the canonical file, but Cursor IDE users may see outdated skill definitions in their editor. The discrepancy creates confusion for developers relying on the `.cursor` path for IDE-based skill inspection, though it does not break agent execution. ### Why does the repository include a .cursor directory? The `.cursor` directory provides compatibility with the Cursor IDE, which expects skill manifests at specific hidden-directory paths. This convention allows Cursor users to browse and interact with skill definitions within their editor while maintaining a clean separation between runtime-critical files and tooling-specific copies.