# How to Sync the Cursor Skill with the Canonical Version in i-have-adhd

> Sync the Cursor skill with the canonical version in i-have-adhd by copying the SKILL.md file to ensure your mirrored skill stays updated with the source of truth. Keep your setup in sync effortlessly.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To sync the Cursor skill with the canonical version, copy [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) to [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) to ensure the Cursor-compatible mirror remains identical to the source of truth.**

The **i-have-adhd** repository maintains its authoritative skill definition in a canonical location that serves as the single source of truth for the project's ADHD assistance capabilities. When you sync the Cursor skill with the canonical version, you ensure that the Cursor runtime at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) reflects the latest rules, wording changes, and metadata adjustments defined in the canonical file. This mirror relationship is documented in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) and requires both files to contain identical Markdown content with matching headers and rule sets.

## Understanding the Canonical and Cursor Skill Structure

The repository stores the definitive skill logic in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This file contains the complete set of assistance rules and configuration in plain Markdown format.

Cursor-compatible runtimes require this same configuration to exist at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md). Because both locations contain the same header and rule set with no runtime-specific logic, a literal file copy maintains the required contract between the canonical source and the Cursor integration.

## How to Sync the Cursor Skill with the Canonical Version

You can maintain synchronization through three approaches depending on whether you need manual updates, automated CI integration, or pre-commit safeguards.

### Manual Synchronization Using Shell Commands

For ad-hoc updates on a developer machine, use a straightforward copy command:

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

```

This immediately overwrites the Cursor version with the canonical contents.

### Automated Synchronization with Node.js

For continuous integration pipelines or frequent updates, implement the following Node.js script at [`scripts/sync-cursor-skill.js`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/sync-cursor-skill.js):

```javascript
#!/usr/bin/env node
/**
 * Synchronize the Cursor skill with the canonical skill definition.
 * Usage: node scripts/sync-cursor-skill.js
 */

import { readFile, writeFile } from 'fs/promises';
import { resolve } from 'path';

async function sync() {
  const src = resolve('skills/i-have-adhd/SKILL.md');
  const dest = resolve('.cursor/skills/i-have-adhd/SKILL.md');

  const [srcContent, destContent] = await Promise.all([
    readFile(src, 'utf8'),
    readFile(dest, 'utf8').catch(() => ''), // treat missing dest as empty
  ]);

  if (srcContent === destContent) {
    console.log('✅ Cursor skill is already up‑to‑date.');
    process.exit(0);
  }

  await writeFile(dest, srcContent, 'utf8');
  console.log('🔄 Updated .cursor/skills/i-have-adhd/SKILL.md from the canonical source.');
}

sync().catch(err => {
  console.error('❌ Sync failed:', err);
  process.exit(1);
});

```

Add the script to your [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json):

```json
{
  "scripts": {
    "sync-cursor-skill": "node scripts/sync-cursor-skill.js"
  }
}

```

Execute `npm run sync-cursor-skill` to perform the synchronization. The script exits with code `0` if files are already synchronized or successfully updated, and code `1` if the operation fails.

### Preventing Drift with Git Hooks

To prevent accidental divergence before committing, add a pre-commit hook that either performs the copy automatically or aborts the commit if the files differ. This ensures you cannot commit changes to the canonical skill without updating the Cursor mirror.

## Verifying the Synchronization

After copying the files, verify integrity through these steps:

1. Run the sync script or manual copy command.

2. Execute the repository's test suite to ensure no downstream breakage:

```bash
python3 -m unittest discover -s tests -v

```

3. Confirm the files match using diff:

```bash
git diff --quiet skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md && echo "No differences"

```

If the tests pass and the diff reports no changes, the synchronization is successful and the Cursor skill reflects the canonical version exactly.

## Summary

- The **canonical skill definition** lives in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and serves as the repository's source of truth
- The **Cursor-compatible mirror** must exist at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) for proper runtime integration
- Use shell `cp` commands for manual updates or the provided Node.js script for CI/CD automation
- Always verify synchronization by running `python3 -m unittest discover` and comparing file contents with `git diff`
- The relationship between these files is documented in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) according to the repository source code

## Frequently Asked Questions

### What happens if the Cursor skill file diverges from the canonical version?

If [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) diverges from the canonical [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), Cursor users may experience inconsistent behavior or outdated assistance rules. The Markdown content must remain identical to maintain the required contract between the canonical source and the Cursor runtime.

### Can I edit the Cursor skill file directly instead of the canonical version?

You should never edit the Cursor skill file directly. Always modify [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) first, then sync the Cursor skill with the canonical version using the copy methods described above. This ensures the source of truth remains in the canonical location and prevents configuration drift.

### Does the synchronization process modify the file content or just copy it?

The synchronization performs a literal file copy without modifying the Markdown content. Because both files use plain Markdown with no runtime-specific logic, a straightforward byte-for-byte copy maintains the required contract and preserves all headers and rules exactly as written in the canonical skill definition.

### How do I integrate this sync into a CI/CD pipeline?

Add the Node.js script to your pipeline configuration and execute `npm run sync-cursor-skill` or `node scripts/sync-cursor-skill.js` during the build process. The script exits with code 0 if files are already synchronized or successfully updated, and code 1 if the operation fails, making it suitable for automated verification steps in GitHub Actions, GitLab CI, or similar platforms.