How the Canonical i-have-adhd Skill Is Synchronized with Its .cursor Mirror in ayghri/i-have-adhd

The canonical skill at skills/i-have-adhd/SKILL.md is kept in sync with its Cursor IDE mirror through a GitHub Actions workflow that fails CI if the files differ, forcing developers to manually copy changes.

The ayghri/i-have-adhd repository maintains a single source of truth for its ADHD-focused assistance skill while supporting multiple runtime environments. The Cursor IDE requires skills to reside in a specific .cursor/skills/ directory structure, necessitating a mirror file that must remain identical to the canonical definition.

Canonical Skill Location vs. Platform-Specific Mirror

The repository uses a clear separation between authoritative content and compatibility copies:

• Canonical source: skills/i-have-adhd/SKILL.md — the master definition
• Cursor mirror: .cursor/skills/i-have-adhd/SKILL.md — IDE-specific copy

The mirror is a regular file, not a symbolic link. This design choice ensures compatibility with Windows clones and GitHub ZIP downloads, where symlinks frequently break.

The cursor-skill-sync.yml Workflow

Synchronization enforcement lives in .github/workflows/cursor-skill-sync.yml. The workflow triggers on two events:

1. Pull requests that modify either the canonical file or its mirror
2. Every push to main

How the Sync Check Works

The workflow contains a single step that uses the Unix cmp command to perform a byte-for-byte comparison:

- name: Fail if the .cursor copy differs from SKILL.md
  run: |
    cmp skills/i-have-adhd/SKILL.md .cursor/skills/i-with-adhd/SKILL.md || {
      echo "::error::.cursor copy is out of sync. Run: cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md"
      exit 1
    }

If cmp detects any difference, the job fails immediately with a actionable error message.

Manual Synchronization Process

When CI fails due to sync drift, developers must propagate changes manually. The workflow error message provides the exact command:

# From repository root

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

This simplicity is intentional — a manual copy operation ensures intentional changes and prevents accidental overwrites.

Why Not Use Symbolic Links?

The repository explicitly avoids symlinks for the .cursor mirror despite their convenience. Regular files guarantee:

• Cross-platform compatibility — Windows Git clients handle regular files predictably
• Archive portability — GitHub ZIP downloads contain valid file contents
• IDE recognition — Cursor reliably discovers skills in the expected structure

Summary

• Canonical skill synchronization relies on CI enforcement rather than automatic copying
• The cmp command in .github/workflows/cursor-skill-sync.yml detects any drift between skills/i-have-adhd/SKILL.md and its .cursor mirror
• Developers must manually run cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md when canonical changes occur
• Regular files instead of symlinks ensure Windows and ZIP download compatibility
• All merges to main require both files to be identical

Frequently Asked Questions

What happens if I only edit the canonical skill file?

CI will fail on your pull request. The workflow runs cmp against both paths and exits with error code 1 if differences exist, blocking merge until you copy the file to .cursor/skills/i-have-adhd/SKILL.md.

Can I edit the .cursor mirror directly instead?

You can, but the workflow will still fail unless you simultaneously update the canonical file. The check is bidirectional — any difference between the two paths triggers the error regardless of which file changed.

Why doesn't the workflow automatically copy the file?

Automatic copying would risk silently overwriting intentional platform-specific customizations. The explicit manual step ensures developers consciously propagate changes and review the mirror location for any needed Cursor-specific adjustments.

Does this sync mechanism work on Windows runners?

Yes. The cmp command is available in GitHub's ubuntu-latest runners, and the mirror file being a regular file means Windows developers can clone, edit, and submit PRs without symlink-related issues.

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