How to Sync Changes Between the Canonical Skill and Its Cursor Mirror in i-have-adhd

The ayghri/i-have-adhd repository uses a dedicated bash script at scripts/sync-cursor.sh to copy the canonical skill definition from skills/i-have-adhd/SKILL.md to the Cursor mirror at .cursor/skills/i-have-adhd/SKILL.md, ensuring both files remain identical before committing.

The i-have-adhd project provides an open-source skill that structures LLM output to be more actionable for readers with ADHD. To support both general runtime environments and the Cursor editor, the project maintains two copies of the skill definition, requiring a specific procedure to sync changes between the canonical skill and its Cursor mirror to prevent configuration drift.

Understanding the Dual-File Architecture

The repository employs a source-of-truth pattern with two distinct file locations:

• Canonical skill – skills/i-have-adhd/SKILL.md contains the definitive rule set and serves as the single source of truth for all skill logic.
• Cursor mirror – .cursor/skills/i-have-adhd/SKILL.md exists solely for Cursor editor compatibility and must remain byte-for-byte identical to the canonical version.

The scripts/sync-cursor.sh utility bridges these locations. Running this script is mandatory after any modification to the canonical file to ensure the Cursor-specific path reflects the latest changes.

Step-by-Step Sync Procedures

Modify the Canonical Source

Always edit skills/i-have-adhd/SKILL.md to add new rules, update existing guidelines, or refactor sections. Never modify the .cursor mirror directly, as the sync script will overwrite those changes.

Execute the Sync Script

From the repository root, run the provided helper script:

./scripts/sync-cursor.sh

The script performs three critical operations:

1. Defines the CANONICAL and MIRROR path variables.
2. Creates the mirror directory structure using mkdir -p if it does not exist.
3. Copies the canonical file to the mirror location using cp.

Upon success, the terminal outputs:

Synced skills/i-have-adhd/SKILL.md to .cursor/skills/i-have-adhd/SKILL.md

Commit Both Files

After synchronization, stage and commit both files together to maintain repository consistency:

git add skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md
git commit -m "Update skill rules and sync Cursor mirror"

Technical Breakdown of the Sync Script

The scripts/sync-cursor.sh implementation uses strict bash error handling and predictable path resolution:

#!/usr/bin/env bash
set -euo pipefail

CANONICAL="skills/i-have-adhd/SKILL.md"
MIRROR=".cursor/skills/i-have-adhd/SKILL.md"

mkdir -p "$(dirname "$MIRROR")"
cp "$CANONICAL" "$MIRROR"

echo "Synced $CANONICAL to $MIRROR"

Key implementation details include:

• set -euo pipefail – Ensures the script exits immediately on error, undefined variables, or pipeline failures.
• mkdir -p "$(dirname "$MIRROR")" – Safely creates the nested .cursor/skills/i-have-adhd/ directory structure without error if it already exists.
• cp "$CANONICAL" "$MIRROR" – Performs a standard copy that preserves file metadata by default.

Manual Sync Alternative

If you prefer not to use the helper script, replicate its behavior manually from the repository root:

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

This achieves the same result as ./scripts/sync-cursor.sh but requires manually ensuring the directory exists before copying.

Summary

• Always edit the canonical skill at skills/i-have-adhd/SKILL.md exclusively; treat the .cursor path as read-only.
• Execute ./scripts/sync-cursor.sh from the repository root after every canonical change to propagate updates.
• The script automatically creates the mirror directory and copies the file using cp.
• Commit both skills/i-have-adhd/SKILL.md and .cursor/skills/i-have-adhd/SKILL.md together to maintain history integrity.
• Running the sync script is required before committing any changes that affect the skill definition.

Frequently Asked Questions

What happens if I edit the Cursor mirror directly?

Any modifications to .cursor/skills/i-have-adhd/SKILL.md will be permanently overwritten the next time ./scripts/sync-cursor.sh executes, causing lost work. The script always copies from the canonical source to the mirror, not bidirectionally.

Can I run the sync script from a subdirectory?

No. The script uses relative paths (skills/i-have-adhd/SKILL.md and .cursor/skills/i-have-adhd/SKILL.md), so you must execute it from the repository root to ensure correct file resolution.

Does the sync script preserve file metadata?

Yes. The standard cp command without flags preserves timestamps and permissions by default on most Unix-like systems, ensuring the mirror file metadata matches the canonical source.

Is the sync script required before every commit?

Yes. Any pull request that modifies the skill definition must include both the updated canonical file and the synchronized mirror file. The project maintainers require this dual-file update to ensure Cursor users receive identical rule sets.

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