If you use both Cursor and Claude Dev/Code, you’ve probably noticed they both want their own configuration folders (.cursor and .claude). Keeping your custom commands, rules, and skills in sync between them usually means a lot of copying and pasting.

Here is a simple way to centralize everything in one .agents folder and use symlinks to keep both tools updated automatically.

How It Works

The Source of Truth: .agents/

Instead of putting files directly into the tool-specific folders, we use a hidden .agents/ directory at the root of the project. This is where the actual files live:

• commands/ – Reusable prompts like generate.md, git-commit-msg.md, or migrate-admin-module.md.
• rules/ – Core guidelines (like 00-core.md) that define how the AI should behave.
• skills/ – Specific domain knowledge, like accessibility standards or performance checklists.

Symlinks in .cursor/ and .claude/

We then create symbolic links (symlinks) inside .cursor/ and .claude/ that point back to the .agents/ folder.

Since these are symlinks, any change you make to a file in .agents/ is immediately reflected in both Cursor and Claude.

Why This is Better

1. No Duplication – You only edit one file.
2. Consistent Behavior – The AI follows the same rules regardless of which editor you’re currently using.
3. Cleaner Git History – We only track the .agents/ folder. The symlinks are gitignored to avoid path issues in CI/CD or linting tools.
4. Automated Setup – New developers don’t have to manually create links. We use a Git hook to handle it.

Automating the Setup with Husky

To make this seamless, you can add a post-checkout hook (often via Husky) that runs every time someone clones the repo or switches branches. This script checks for the .agents folder and creates the necessary symlinks if they don’t exist.

echo "🔗 Setting up agent symlinks..."

REPO_ROOT="$(git rev-parse --show-toplevel)"
AGENTS_DIR="$REPO_ROOT/.agents"

if [ ! -d "$AGENTS_DIR" ]; then
  echo "⚠️  .agents directory not found, skipping symlink setup"
  exit 0
fi

for subdir in "$AGENTS_DIR"/*/; do
  name="$(basename "$subdir")"

  for target_dir in "$REPO_ROOT/.cursor" "$REPO_ROOT/.claude"; do
    mkdir -p "$target_dir"
    link="$target_dir/$name"

    if [ -L "$link" ]; then
      # Already a symlink — skip
      continue
    elif [ -e "$link" ]; then
      echo "⚠️  $link exists and is not a symlink, skipping"
      continue
    fi

    ln -s "../.agents/$name" "$link"
    echo "  ✅ $link -> ../.agents/$name"
  done
done

echo "🎉 Agent symlinks ready!"

Git Configuration

To keep things tidy, add the following to your .gitignore:

.cursor/commands
.cursor/rules
.cursor/skills
.claude/commands
.claude/rules
.claude/skills

All your actual configuration content should be tracked under the .agents/ directory.

Summary

Centralizing your AI config in .agents and symlinking it to .cursor and .claude is the easiest way to keep your development environment consistent. It reduces the friction of switching tools and ensures your AI “coworker” always has the latest instructions.