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

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 remains identical to the canonical 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 is a physical file that must be manually synchronized with the canonical source at 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, 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. 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 or .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:

- 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 directs developers to run a simple copy command after editing the canonical skill file:

# 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 as a physical file, not a symlink, ensuring Windows and ZIP compatibility.
• CI enforcement occurs in .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.

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, 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 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; 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.

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