How the Cursor Compatible Copy of SKILL.md Is Automatically Maintained in i-have-adhd

The Cursor compatible copy of SKILL.md is maintained automatically through a GitHub Actions workflow that compares the canonical skill definition against the Cursor-specific copy on every push to main, enforcing synchronization by failing the build if the files differ.

The ayghri/i-have-adhd repository manages ADHD-focused development guidelines as structured skill files. Because the Cursor IDE requires skill definitions to reside in a .cursor directory while the repository maintains a canonical source elsewhere, the project uses continuous integration to prevent configuration drift.

Repository Structure and File Locations

The synchronization strategy relies on a clear separation between the source of truth and the editor-specific copy.

The Canonical Source

The primary skill definition lives at skills/i-have-adhd/SKILL.md. This file contains the authoritative rules and guidelines that define the project's ADHD-aware development approach. All edits to the skill logic must originate here.

The Cursor Copy

Cursor IDE expects skill files in a specific directory structure. Consequently, the repository maintains a duplicate at .cursor/skills/i-have-adhd/SKILL.md. This file must remain byte-for-byte identical to the canonical version for the integration to function correctly.

The Synchronization Workflow

The .github/workflows/cursor-skill-sync.yml file defines the automated pipeline that enforces consistency between these two locations.

Workflow Trigger and Configuration

The workflow activates on every push to the main branch. According to the workflow configuration, it specifically monitors both file paths: skills/i-have-adhd/SKILL.md and .cursor/skills/i-have-adhd/SKILL.md.

File Comparison Logic

At line 22 of the workflow file, the pipeline executes the cmp command to perform a binary comparison:

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

The cmp utility compares the two files byte by byte. If the files differ in any way, the command returns a non-zero exit code, triggering the failure path.

Error Handling and Enforcement

When cmp detects a mismatch, the workflow immediately reports an error and blocks the merge. Lines 20-23 of the workflow implement this fail-fast behavior, emitting the following error message:

::error::.cursor copy is out of sync. Run: cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

This enforcement ensures that developers cannot accidentally merge changes that would desynchronize the Cursor compatible copy of SKILL.md from its canonical source.

Manual Synchronization Process

If the CI pipeline detects drift, developers must manually align the files before the pull request can merge. The workflow suggests the exact command needed to synchronize the files:

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

After executing this command and committing the result, the workflow will pass on the subsequent push, confirming that the Cursor compatible copy of SKILL.md matches the source of truth.

Summary

• The canonical skill definition resides in skills/i-have-adhd/SKILL.md and serves as the single source of truth.
• Cursor IDE requires a duplicate at .cursor/skills/i-have-adhd/SKILL.md for proper integration.
• The .github/workflows/cursor-skill-sync.yml workflow runs automatically on every push to main.
• The cmp command performs a byte-level comparison to detect any divergence between the files.
• If files differ, the workflow fails immediately and provides the exact cp command needed to resynchronize them.
• This automation eliminates manual copying and guarantees that the Cursor compatible copy of SKILL.md always reflects the current project standards.

Frequently Asked Questions

Why does the repository need two copies of SKILL.md?

Cursor IDE expects skill definitions to exist within a .cursor directory structure to recognize and load them properly. However, the project maintains its canonical configuration in a skills directory to remain editor-agnostic and clearly signal where the authoritative definition lives. The dual-file approach supports Cursor compatibility without tying the entire repository structure to a single editor's conventions.

What happens if I edit only the .cursor copy and not the canonical file?

The workflow will fail because it compares skills/i-have-adhd/SKILL.md against .cursor/skills/i-have-adhd/SKILL.md using the cmp command. Since the canonical file would remain unchanged while the Cursor copy differs, the comparison detects a mismatch and blocks the merge with an error message instructing you to copy from the canonical location.

Can I disable the synchronization check in my fork?

While you could modify .github/workflows/cursor-skill-sync.yml to remove the comparison step or the fail-fast behavior, doing so would break the guarantee that Cursor users receive the correct skill configuration. The workflow is designed as a safety mechanism to ensure both files remain in lockstep across all contributions.

Does the workflow automatically copy the file when it detects changes?

No, the workflow does not automatically copy the file. It only detects differences and fails the build. The workflow explicitly requires manual intervention using the suggested cp command. This design ensures that developers consciously review and commit the synchronized change, preventing accidental overwrites and maintaining clear version control history for both file locations.

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