SKILL.md and Its .cursor Mirror File: Purpose and Differences in the i-have-adhd Repository

The canonical 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. 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, 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. This file is not used by any runtime or agent harness. Instead, it exists solely to satisfy the Cursor IDE's expectation of finding a skill manifest at that specific hidden-directory location.

As noted in 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): 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): 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, any modification to the canonical SKILL.md must be mirrored to the .cursor directory to maintain consistency. Use the following workflow after editing the primary file:

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

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

/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 at 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 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.
• 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. 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, 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.

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