# How the Cursor Mirror of the i-Have-ADHD Skill Is Synchronized

> Learn how the Cursor mirror for the i-have-adhd skill synchronizes via a CI-enforced manual copy workflow. Discover the technical details behind this synchronization process.

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

---

**The Cursor mirror is synchronized through a manual copy workflow enforced by CI, where a GitHub Actions job uses the `cmp` command to verify that [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) remains identical to the canonical [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), failing the build and prompting contributors to run `cp` if the files diverge.**

The `ayghri/i-have-adhd` repository maintains a **Cursor-compatible mirror** of its core skill definition to ensure compatibility across all operating systems, including Windows environments where symbolic links fail. Unlike a symlink, the mirror at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) is a physical file that must be manually synchronized with the canonical source at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). Understanding exactly how the Cursor mirror of the i-have-adhd skill is synchronized ensures that contributions remain valid across both Cursor and standard installations.

## Why the Repository Uses a Physical File Instead of a Symlink

Many open-source projects use symbolic links to duplicate files, but the `i-have-adhd` project explicitly avoids them. Symbolic links break on Windows default configurations and vanish when users download the repository as a ZIP archive from GitHub. By placing a real file at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md), the repository guarantees that the Cursor IDE can locate and load the skill definition regardless of the user's extraction method or OS.

## The CI Workflow That Enforces Synchronization

The repository automates validation through [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml). This workflow acts as a gatekeeper, ensuring that any edit to the skill definition is reflected in both locations before code reaches the `main` branch.

### Workflow Triggers and Scope

According to the source configuration, the job executes on two conditions:

- When a pull request modifies either [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) or [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)
- On every push to the `main` branch

This dual trigger ensures that direct commits and community contributions alike undergo the same scrutiny.

### The cmp Check and Error Handling

Inside the workflow, the core logic relies on the Unix `cmp` command to perform a byte-level comparison:

```yaml
- name: Fail if the .cursor copy differs from SKILL.md
  run: |
    cmp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-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 script emits a GitHub Actions error annotation and terminates with exit code 1. This immediately blocks the merge and surfaces an explicit remediation command in the CI logs.

## How Contributors Manually Synchronize the Mirror

Because the CI only validates and does not auto-commit, contributors must execute the synchronization manually. The project documentation in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) directs developers to run a simple copy command after editing the canonical skill file:

```bash

# Update the Cursor mirror after modifying the canonical skill

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

```

This one-line operation duplicates the content to the hidden `.cursor` directory, satisfying the `cmp` check in the subsequent CI run. Maintainers treat this step as mandatory; PRs with desynchronized mirrors will fail status checks regardless of the content quality.

## Summary

- The **Cursor mirror** resides at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) as a physical file, not a symlink, ensuring Windows and ZIP compatibility.
- **CI enforcement** occurs in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml), which triggers on relevant PRs and `main` branch pushes.
- The `cmp` command performs a strict binary comparison; mismatches fail the build and print a corrective `cp` command.
- Contributors must manually run `cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md` after editing the canonical skill, as documented in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md).

## Frequently Asked Questions

### Why doesn't the repository use a symbolic link for the Cursor mirror?

Symbolic links are not universally supported across operating systems; they break on Windows default configurations and disappear when users download the repository as a ZIP archive from GitHub. By using a real file at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md), the project guarantees that the Cursor IDE can load the skill definition in every environment.

### What happens if I edit the skill but forget to update the .cursor copy?

The GitHub Actions workflow defined in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) will detect the discrepancy using `cmp` and fail the CI check. The error message explicitly instructs you to run `cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md`, preventing the PR from merging until the mirror is updated.

### Can I edit the .cursor file directly and skip the canonical one?

While technically possible, this approach violates the repository's structure. The canonical source of truth is [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md); the `.cursor` path is strictly a derivative copy. Editing only the mirror would cause the canonical version to become outdated, and subsequent contributors editing the canonical file would overwrite your changes. Always edit the canonical file first, then copy it to the Cursor directory.

### Does the CI workflow automatically fix the synchronization if it finds a mismatch?

No, the workflow is intentionally read-only to prevent automated commits from obscuring contributor intent. It only validates that the files match using `cmp`; it does not execute the `cp` command or commit changes. You must manually perform the copy and push the result before the CI check will pass.