Cursor Rules、Skills、Agentsをdotfilesで管理してみたが、Subagentsだけはシンボリックリンクを認識しなかった話

はじめに

以前、知り合いから「GNU Stowを使うとdotfilesの管理が楽になるよ」と教えてもらったので、GNU Stowについて色々調べてみて実際に使ってみた。

使ってみた感じとしてはシンボリックリンクの管理をよしなにやってくれる便利ツールで、これは大変便利だと感じました。

さっそく、自分のdotfilesにも適応してみたのだが、「ん？まてよ、これがあればCursor Rules、Skills、AgentsやGitHub Copilotのinstructionsなんかも便利に管理できるんじゃない？」と思い、試してみました。

背景

私の仕事のスタイルとして、1つの案件で特定のワークスペースを長く使って作業をするのではなく、複数案件掛け持ちで複数のワークスペースを切り替えて作業する仕事の方が多いので、個人で使っているRules、Skills、Agentsなどは、$HOME直下の.cursorで管理しています。

そこで、dotfilesに、$HOME直下においてある.cursorのRules、Skills、Agentsをおいてみて、stowコマンドでシンボリックリンクを貼ることにしました。

方法

dotfilesの中に、Cursor Rules、Skills、Agentsを配置するだけです。

dotfiles
└── ws-cursor
    └── .cursor
        ├── agents
        │   ├── code-reviewer.md
        │   ├── planner.md
        │   ├── security-reviewer.md
        │   └── tdd-guide.md
        ├── AGENTS.md
        ├── rules
        │   ├── common-agents.mdc
        │   ├── common-coding-style.mdc
        │   ├── common-development-workflow.mdc
        │   ├── common-git-workflow.mdc
        │   ├── common-patterns.mdc
        │   ├── common-security.mdc
        │   └── common-testing.mdc
        └── skills
            ├── documentation-lookup
            │   └── SKILL.md
            ├── github-commit-message
            │   └── SKILL.md
            ├── github-pull-request
            │   └── SKILL.md
            └── github-pull-request-review
                └── SKILL.md

あとは、$HOMEにて以下コマンドを実行してみました。

stow --no-folding -d ~/dotfiles -t . ws-cursor

なお、同名のファイルがすでに存在した場合、そのファイルだけがシンボリックリンクに失敗するので、既存のファイルが上書きされる心配もありません。

これは便利・・・と、思いきや、

SubAgentsが認識されない！！！

原因を調べたところ、RulesやSkillsは問題ないのですが、Agentsだけは、 シンボリックリンク先のファイルを認識しません でした。

なんてこったい。。。

さらに調査を進めたところ、どうやらagentsフォルダ自体にシンボリックリンクを貼ってやれば、認識してくれる様でした。

というわけで、以下スクリプトを作る（AIに書いてもらう）ことに。。。

~/dotfiles/scripts/setup-cursor-project.sh

#!/bin/bash
# Cursor プロジェクトに ws-cursor dotfiles をセットアップするスクリプト
#
# 使い方:
#   cd ${Workspace}
#   ~/dotfiles/scripts/setup-cursor-project.sh
#
# または対象ディレクトリを引数で指定:
#   ~/dotfiles/scripts/setup-cursor-project.sh /path/to/project

set -euo pipefail

DOTFILES_DIR="$(cd "$(dirname "$0")/.." && pwd)"
TARGET="${1:-$(pwd)}"

echo "Setting up Cursor project dotfiles..."
echo "  dotfiles: $DOTFILES_DIR"
echo "  target:   $TARGET"

# rules / skills をファイル単位のシンボリックリンクで展開（agentsは除外）
stow --no-folding --ignore='agents' -d "$DOTFILES_DIR" -t "$TARGET" ws-cursor

# agents はフォルダごとシンボリックリンクにする
# （Cursor はファイル単位のシンボリックリンクを Subagent として認識しないため）
AGENTS_LINK="$TARGET/.cursor/agents"
AGENTS_SRC="$DOTFILES_DIR/ws-cursor/.cursor/agents"

if [ -L "$AGENTS_LINK" ]; then
  echo "agents symlink already exists, skipping."
elif [ -d "$AGENTS_LINK" ]; then
  rm -rf "$AGENTS_LINK"
  ln -s "$AGENTS_SRC" "$AGENTS_LINK"
  echo "Replaced agents directory with folder symlink."
else
  ln -s "$AGENTS_SRC" "$AGENTS_LINK"
  echo "Created agents folder symlink."
fi

echo "Done."

$HOMEにて以下コマンドを実行してみたところ、無事Subagentを含めてすべて認識してくれました。

~/dotfiles/scripts/setup-cursor-project.sh

さいごに

AIのこうしたRules、Skills、Agentsもdotfailesで管理できたら便利なのに、まさかシンボリックリンクにすると認識しなくなるとは思いませんでした。（しかも、Subagentだけ）

とはいえ、便利なので、しばらくはdotfilesで管理していこうかと思います。