Cursor Agent Skills インストールとチーム設定

「インストールしたはずのスキルがCursorに出ない」
最短解は、対象リポジトリのルートで npx skills@latest add mattpocock/skills を実行し、setup-matt-pocock-skills を選んでから、Cursor Agentで手動実行することです。プロジェクト固有の手順はSkills、常時守る規約はCursor Rulesに分けてください。Claude Codeを使うメンバーは、プラグイン方式と編集可能なファイル方式のどちらか一方だけを選びます。

対象者と前提条件

この記事は、CursorでTDD、障害診断、コードレビューをすぐ使いたい個人開発者向けです。複数メンバーのAgent挙動をそろえ、設定をGitで管理したい技術責任者にも向いています。ローカル環境とリモートMac環境の開発手順をそろえたいチームは、まず本稿のローカル検証を完了させてください。

CursorはAgent SkillsをエディターとCLIで扱えます。スキルは SKILL.md を中心に、必要なスクリプトや参照資料をまとめる仕組みです。常時読み込む宣言的なRulesに対し、Skillsはタスクに応じて発見・適用される手順や専門知識を置く場所です。Cursor 2.4公式更新履歴

プロジェクト配置と全体設定の切り分け

チームのリポジトリで使うなら、基本はプロジェクト単位です。npx skills@latest add ... は、いまいるディレクトリを基準に書き込むため、対象リポジトリのルートで実行します。別のリポジトリを開いたまま実行すると、正しいSkillを入れたのにCursorで見えない、という事故が起きます。

Cursorが検出する候補は、プロジェクト側の .cursor/skills/<skill-name>/SKILL.md と .agents/skills/<skill-name>/SKILL.md、ユーザー側の ~/.cursor/skills/ と ~/.agents/skills/ です。チームでレビューし、ブランチごとに再現したいファイルはプロジェクト側へ置きます。個人専用の実験用Skillや自分だけの補助はユーザー側に残します。配置と SKILL.md の構造は、CursorのAgent Skills仕様 を導入時に照合してください。

導入前には、次を確認します。

• Node.jsとGitが実行できる。
• 対象リポジトリに書き込み権限がある。
• 未コミット変更を避けるため、専用ブランチを用意する。
• Cursorで開いているフォルダーが、コマンドを実行するリポジトリと一致している。
• Claude Codeのプラグイン方式を、同じSkillのファイル方式と併用していない。

最後の点は重要です。mattpocock/skillsのREADMEは、Claude Codeプラグインを管理対象の読み取り専用セット、skills.sh方式を自分で編集するファイルとして説明し、両方を入れると同じSkillが重複すると警告しています。mattpocock/skills README

skills.sh方式の初回導入

Cursorを主対象にするなら、skills.sh のCLI方式を選びます。リポジトリのルートで、次のコマンドを実行してください。

npx skills@latest add mattpocock/skills

インストーラーでは、導入するSkillと対象Agentを選択します。最初の選択では、必ず setup-matt-pocock-skills を含めます。TDD、diagnosing-bugs、code-review などは、チームが実際に使う工程だけを選んでください。すべてを最初から有効にすると、候補が増え、Agentが意図しない手順を拾う原因になります。利用可能なSkill名は、公開ページの表示ではなく、skills.shの現在の一覧 と導入時の選択画面で確認します。

導入直後は、ファイルを確認します。

find .cursor .agents -name SKILL.md -print 2>/dev/null
git status --short
git diff -- .cursor .agents

SKILL.md がSkill名のフォルダー内にあるか、別リポジトリへ書き込まれていないか、差分に個人情報や不要なスクリプトがないかを見ます。インストール成功の表示だけで判断しないでください。Cursorが読むのは、ファイル名、階層、前置きメタデータがそろったSkillです。

setup実行と見えない場合の切り分け

Cursor Agentで、次を手動実行します。

/setup-matt-pocock-skills

このSkillは、課題管理の場所、トリアージ用ラベル、ドキュメントの保存場所を確認し、リポジトリの設定として記録します。実装を自動で固定するスクリプトではなく、既存のGit設定や文書を調べ、候補を提示してから書き込む対話型の初期設定です。setup-matt-pocock-skillsの仕様

ここで決めた内容は、チームでレビューできる形にします。たとえば課題管理の種類、トリアージラベル、ドメイン文書の場所を、生成された docs/agents/ 以下のファイルで確認します。既存の AGENTS.md または CLAUDE.md に追加された Agent skills の案内も、差分として確認してください。

SkillがCursorに表示されない場合は、次の順番で調べます。

• .cursor/skills/<名前>/SKILL.md または .agents/skills/<名前>/SKILL.md の階層になっているか。
• ファイル名が正確に SKILL.md か。
• name と description の前置きメタデータがあるか。
• disable-model-invocation: true が付いていないか。
• Cursorの設定画面やAgentの / メニューに表示されるか。
• ファイルを追加したあと、Cursorを再読み込みまたは再起動したか。

手動のスラッシュ呼び出しと自動発見は別です。disable-model-invocation が有効なSkillは、Agentの自動判断から外し、明示的な /skill-name で使う設計になります。表示場所と自動実行の可否を混同しないでください。

SkillsとRulesの責任分界

Cursor Rulesには、毎回守るべき長期的な制約を置きます。たとえば、使用言語、命名規則、テスト必須、禁止ライブラリ、レビュー方針です。一方、Skillsには、要件を聞き出す手順、TDDの進め方、障害診断の確認順、コードレビューの観点など、必要なときだけ実行する工程を置きます。

判断に迷ったら、次の分け方にします。

• すべての変更に適用する規約 → Cursor Rules
• 特定の作業でだけ使う手順 → Skills
• 外部コマンドやスクリプトを呼ぶ流れ → Skills
• 長期に変わらない禁止事項や設計原則 → Cursor Rules
• チームで議論しながら改善する実験的な作業手順 → プロジェクト側のSkill

たとえば「テストを追加する」はTDD Skill、「本番コードには必ず型を付ける」はRulesです。両方へ同じ説明を書くと、修正漏れと優先順位の衝突が起きます。Cursor公式も、Rulesは静的なコンテキスト、Skillsは必要時に読み込む動的な能力として整理しています。CursorのAgent活用ガイド

小さな実装での受け入れ確認

導入後は、大きな機能開発ではなく、小さな実タスクで確認します。要件が曖昧なら要件整理系のSkill、テスト先行ならTDD、既存障害なら診断系、差分確認ならコードレビュー系というように、工程ごとに呼び分けます。

確認する成果物は、次のように具体化します。

• Skillが / メニューに表示される。
• Agentが説明文に一致する場面でSkillを候補にする。
• Skill内で参照するスクリプトや文書が、実際のリポジトリに存在する。
• setup-mattpocock-skills の結果が docs/agents/ に残る。
• 変更差分を別メンバーが読んでも、個人環境の前提に依存していない。
• 失敗時に、Skillを外しても通常のCursor作業へ戻れる。

チーム導入の確認リスト

• [ ] リポジトリのルートで導入コマンドを実行した。
• [ ] setup-mattpocock-skills を初回選択に含めた。
• [ ] Skillのファイルをプロジェクト側へ保存した。
• [ ] SKILL.md の階層と前置きメタデータを確認した。
• [ ] RulesとSkillsに同じ指示を重複記載していない。
• [ ] 生成された docs/agents/ と AGENTS.md または CLAUDE.md をレビューした。
• [ ] TDD、診断、レビューの小さな実タスクで呼び出しを確認した。
• [ ] 第三者Skillのスクリプト、参照ファイル、実行権限を確認した。
• [ ] 上流更新を直接上書きせず、差分確認用のブランチで試した。

更新運用と方式比較

mattpocock/skills は、導入して終わりではありません。更新前に上流READMEと変更差分を読み、チームで追加した説明やスクリプトが消えないかを確認します。そのうえで、検証用ブランチへ反映し、代表的なタスクを再実行してから本流へ取り込みます。更新コマンドは、公開READMEとskills CLIの案内を実行時点で確認してください。

Claude Codeの利用者がいる場合は、プラグインか skills.sh の編集可能なファイルかを先に決めます。二重導入はSkill名の重複だけでなく、どの説明や更新元を基準にするかも曖昧にします。

現在の環境からMac開発へ移す判断

既存の開発環境だけで運用する場合、個人ごとのNode.js、Cursor設定、権限、再読み込み手順がずれやすく、Skillの発見状態を毎回確認する負担が残ります。さらに、設定をユーザー側へ置くとGitレビューができず、上流更新でチーム固有の変更を失う危険もあります。

まずローカルで本稿のチェックを完了し、その後にMacの開発ワークスペースへ同じリポジトリを展開して差分を確認してください。再現可能な初期化手順や運用上の権限整理が必要なら、MacHTMLのサポート情報と利用コンソールを確認し、チームで固定すべき作業と個人設定を切り分けるのが安全です。長期的な高負荷処理や物理デバイス接続が前提なら自前のMacが適し、短期検証やメンバー間で同じ作業環境を再現したい場合に、MacHTMLのMac環境を比較対象に入れる価値があります。