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

> Discover how the canonical i-have-adhd skill syncs with its Cursor IDE mirror using GitHub Actions. Learn about the CI failure mechanism that ensures file consistency and requires manual updates.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: internals
- Published: 2026-08-18

---

**The canonical skill at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) — the master definition
- **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) — 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`](https://github.com/ayghri/i-have-adhd/blob/main/.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**:

```yaml
- 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:

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) detects any drift between [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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.