Functional Difference Between the Main Skill Definition and Its Cursor Mirror

The main skill definition and its Cursor mirror are functionally identical; the mirror exists solely for Cursor IDE compatibility while the canonical file drives runtime execution.

The ayghri/i-have-adhd repository maintains duplicate skill definitions to support both the core runtime and the Cursor editor environment. Understanding the functional difference between the main skill definition and its Cursor mirror ensures you edit the correct file when customizing ADHD-friendly development rules. The repository explicitly documents this duality in AGENTS.md to prevent configuration drift between the runtime engine and the editor experience.

Canonical Skill Definition vs. Cursor Mirror

The repository stores the i-have-adhd skill in two locations with distinct operational purposes, though both files contain exactly the same markdown content.

The Canonical Runtime File (skills/i-have-adhd/SKILL.md)

This is the canonical skill definition consumed by the core runtime engine. When you invoke the skill via /i-have-adhd, the engine reads skills/i-have-adhd/SKILL.md and applies the 10 ADHD-friendly rules defined within the file.

<!-- Runtime invocation -->
/i-have-adhd

The Cursor Mirror (.cursor/skills/i-have-adhd/SKILL.md)

This is a Cursor-compatible mirror located in the .cursor/skills/ directory. Cursor expects a SKILL.md inside a .cursor/skills/... path to provide language-model-driven assistance within the editor. This mirror allows Cursor users to receive the same skill metadata without the repository modifying its core layout to match Cursor-specific conventions.

Why the Mirror Exists

The mirror solves a tooling compatibility constraint without polluting the canonical source structure. Cursor's IDE plugin looks for skill definitions within .cursor/skills/{skill-name}/ to populate its AI assistance context. By maintaining a copy in this location, the repository supports Cursor's conventions while keeping the runtime's file-loading logic simple and predictable.

According to the source analysis, the runtime never reads the .cursor/ directory; it is reserved entirely for editor-specific configurations.

Execution Flow and File Loading

Understanding which file the system reads is critical for debugging skill behavior and ensuring consistency.

When the skill engine initializes, it explicitly loads the definition from skills/i-have-adhd/SKILL.md. The engine ignores the .cursor/ directory entirely, meaning changes to the mirror have zero effect on execution.

When you open the project in Cursor, the editor loads the content from .cursor/skills/i-have-adhd/SKILL.md to provide inline suggestions. Because both files contain identical markdown, the ADHD-friendly rules remain consistent whether the skill is executed by the runtime or referenced by the Cursor AI.

Maintaining Synchronization

Because the runtime only reads the canonical file, all changes must originate in skills/i-have-adhd/SKILL.md. You should then sync those changes to .cursor/skills/i-have-adhd/SKILL.md to keep the Cursor editor experience consistent. If the files diverge, Cursor will suggest outdated rules while the runtime executes current ones.

Use a simple copy command to refresh the mirror after editing the canonical definition:

# Edit the canonical skill definition

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

# Sync to Cursor mirror

cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

Summary

• The canonical file at skills/i-have-adhd/SKILL.md drives all runtime execution and contains the 10 ADHD-friendly rules.
• The Cursor mirror at .cursor/skills/i-have-adhd/SKILL.md provides IDE compatibility but is ignored by the runtime engine.
• Both files must contain identical markdown content to ensure consistent behavior between the editor and the execution environment.
• Always update the canonical file first, then sync to the mirror to maintain parity.

Frequently Asked Questions

Does the Cursor mirror affect how the skill executes?

No. The runtime engine explicitly loads the skill from skills/i-have-adhd/SKILL.md and ignores the .cursor/ directory entirely. The mirror is only read by the Cursor editor plugin to provide language-model-driven assistance, not by the execution engine.

Which file should I edit to change the skill behavior?

Always edit skills/i-have-adhd/SKILL.md first. This is the canonical source that the runtime uses. You should then copy those changes to .cursor/skills/i-have-adhd/SKILL.md to ensure the Cursor editor suggests the updated rules.

Are the two files always identical in content?

Yes. According to the repository's AGENTS.md and source analysis, both files contain exactly the same markdown content. Any divergence between the canonical definition and the Cursor mirror means the editor and runtime will behave differently, which violates the repository's design intent.

Why doesn't Cursor just read from the main skills/ directory?

Cursor's IDE expects skill definitions in a specific .cursor/skills/ path to provide context-aware AI assistance. The mirror allows the repository to maintain its own structural conventions (placing skills in skills/) while still supporting Cursor's specific path requirements for editor integration.

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