はじめに

Cursor でエージェントを動かし始めると、いつの間にか Skill が30個 になっていたり、同じ注意書きが Rule と AGENTS.md に二重 になっていたりします（笑）

この記事では、私がこの Qiita ブログリポジトリで試している 5レイヤーの分け方 をまとめます。

Skill（.cursor/skills/）
Subagent（.cursor/agents/）
Rule（.cursor/rules/）
Hook（git hook / Cursor hooks）
入口ドキュメント（AGENTS.md）

設計の出発点は Claude Academy — Introduction to Agent Skills です（旧 URL: anthropic.skilljar.com）。Cursor でも Agent Skills の考え方が広がっており、皆が Anthropic の型を真似する なら、最初からアカデミーの流れに寄せた方が迷いが少ない、というのが私の結論です。

この記事で分かること:

5レイヤーそれぞれに 何を書くか・何を書かないか
「Skill を増やす → サブエージェントに逃がす → Rule で重複を1箇所に」 というスリム化のループ
エージェントに 「どんな Skill があったら便利？」 と聞き続けて、提案が出なくなるまで skills 化するやり方

想定読者

Cursor の Agent Skills を増やしすぎて、整理の仕方が分からなくなった方
Rules / Hooks / Subagents / AGENTS.md の違いをざっくり掴みたい方
使い捨てSkills や Kaggle用Skill分離を読んで、長く使うリポジトリ ではどうするか知りたい方

私の属性

エディターは Cursor がメイン。ハッカソン・Kaggle・Qiita 執筆と、開くフォルダがコロコロ変わる
このブログは Qiita CLI + GitHub Actions で運用（執筆環境の記事）
Kaggle 側では Skill を コンペフォルダだけに閉じる 設計をしている（0011）

結論 — 5レイヤーの役割

レイヤー	置き場	役割（一言）
Skill	`.cursor/skills/<name>/SKILL.md`	手順・判断・ワークフロー
Subagent	`.cursor/agents/*.md`	重い探索・読み取り専用調査の委譲
Rule	`.cursor/rules/*.mdc`	短い常時リマインド（ゲート・禁止）
Hook	`.cursor/hooks.json` / git hook	イベント駆動の機械的ブロック
入口	`AGENTS.md`	セッション開始時の全体像と Skill 一覧

長い手順は Skill、1行で済む禁止事項は Rule、探索は Subagent、絶対にやらせたくない操作は Hook、地図は AGENTS.md — これだけ覚えればだいたい迷いません。

アカデミーでは外部連携として MCP も並びますが、本記事の5レイヤー外（ツール接続）として扱います。

公式の型は Anthropic 側が先に整理してくれています。Cursor 固有の置き場は Cursor 公式ドキュメントを見ますが、SKILL.md の frontmatter（name / description）と「必要なときだけ読む」 という発想は、アカデミーと同じです。

Claude Academy を設計の土台にする

Introduction to Agent Skills では、Skill を 「新人へのオンボーディング資料」 のようにパッケージ化する、と説明されています。

フォルダに SKILL.md を置く
YAML frontmatter に 何の Skill か・いつ使うか を書く
本文に手順・判断基準を書く
必要なら reference.md やスクリプトを同梱する

Cursor でも .cursor/skills/<name>/SKILL.md は同じ形です。周辺ツールが増えても この形がデファクト になりつつあるので、わざわざ独自フォーマットを考えず、アカデミー通りに作っておくと、あとから他の記事や anthropics/skills の例をそのまま借りられます。

公式が読む Skill の場所は複数あります（Skills 公式）。プロジェクトなら .cursor/skills/ と .agents/skills/、ユーザー級なら ~/.cursor/skills/ と ~/.agents/skills/。互換のため .claude/skills/ や .codex/skills/ も拾います。この記事の例とツリーは、すべて .cursor/skills/ 前提です。

参考リンク:

Claude Academy — Introduction to Agent Skills（旧: anthropic.skilljar.com）
Equipping agents for the real world with Agent Skills（エンジニアリングブログ）
agentskills.io（オープン標準）

Skill は「エージェントに聞いて」増やす

Skill の候補は、最初から自分で全部列挙しなくてよい、という運用にしています。

チャットで例えばこう聞きます。

このリポジトリで記事を書くとき、どんな Skill があったら便利？ないものは「○○ Skill を作ると、△△に役立つ」と提案して。

するとエージェントは、だいたい次のような提案を返してくれます。

「投稿前ゲートを忘れがちなら qiita-cli Skill に promote 手順をまとめると安全」
「文体チェックは style-guide.md を Skill の references に置くと推敲が安定する」
「キャンペーン UUID の履歴管理は qiita-campaigns Skill に切り出すとよい」

提案がまだ出る限り skills 化を続ける。 「もう新しい Skill の提案はない？」と聞き、同じような案が繰り返されるだけになったら一区切り、という止め方です。

ポイント:

1 Skill = 1つの判断領域（執筆 / CLI / キャンペーン / クロスリファレンス…）
本文は短く、詳細は同フォルダの reference.md へ逃がす（500行目安）
description に トリガー語（「promote」「内部リンク」など）を入れて、自動で読まれるようにする

このブログでは例えば次のように分けています。

Skill	いつ読まれるか
`qiita-blog-writing`	記事の企画・執筆・推敲
`qiita-cli`	投稿・preview・Markdown 記法
`qiita-cross-reference`	公開記事の検索・内部リンク
`qiita-campaigns`	投稿キャンペーンの同期
`cursor-agent-tooling`	Skills / Rules 自体の改修（メタ）

コンテキストが重くなったら Subagent に逃がす

Skill を増やすほど、親チャットのコンテキスト が膨らみます。Kaggle 用リポジトリでは Skill が約30個あり、「コンペによって使わない Skill も多い」と感じたので、別の逃がし方を試しました（0011）。

読むだけの重い仕事は Subagent に委譲し、親にはサマリだけ返す。

親エージェントがやること	Subagent に任せること
執筆方針の決定	`public/` 全体のキーワード検索
ユーザーへの確認	候補記事の見出し・該当段落の読み取り
承認後のリンク挿入	スコア付き候補リストの作成

このブログでは cross-reference-researcher を .cursor/agents/ に1つだけ置いています。npm run search:articles を何度も回して関連記事を探す作業は、親チャットにログを溜めないためです。

Subagent の設計メモ:

2〜4個に絞る（汎用ヘルパーの乱立は逆効果）
探索系は readonly: true にすると、勝手に promote されない
出力フォーマットを Subagent 定義に書いておく（親がコピペしやすい）

Rule と Hook — 短い禁止と機械的ブロック

Skill に「絶対に promote するな」と長文で書いても、セッションが長くなると忘れがちです。常時効く短いリマインドは Rule に寄せます。

例: .cursor/rules/qiita-publish-gate.mdc

drafts/ は編集 OK、public/ への promote と push はユーザー明示まで禁止
alwaysApply: true は 本当に守らせたいゲートだけ（増やしすぎない）

一方 Hook は人間の判断を介さず止めたいとき に使います。ここは2種類あり、混同しやすいです。

種類	置き場	いつ動くか
Cursor Hooks	`.cursor/hooks.json` + スクリプト	エージェントのライフサイクル（ツール実行前後など）。Academy の「event-driven」に近い
Git hooks	`scripts/hooks/` → `.git/hooks/`	`git commit` など Git 操作の直前

このブログリポジトリの実例は git 側 です。pre-commit で .env やトークンっぽい文字列のステージをブロックし、npm run install:hooks で導入しています。Cursor Hooks（.cursor/hooks.json）はまだ置いていません。

やりたいこと	向いているレイヤー
「promote するな」と毎回思い出させたい	Rule
エージェントの危険なツール実行を止めたい	Cursor Hooks（`.cursor/hooks.json`）
秘匿ファイルをコミットさせたくない	Git hook（本リポの例）
promote の手順と例外条件を説明したい	Skill
投稿フローの地図を見せたい	AGENTS.md

同じ注意書きを Skill と Rule の両方に丸写ししない。 詳細は Skill、一行の禁止は Rule、という役割分担にします。

AGENTS.md — 入口に地図だけ書く

AGENTS.md は セッション開始時にエージェントが最初に見る地図 です。

書くこと:

リポジトリの目的（何のプロジェクトか）
ディレクトリ構成の概要
Skill / Subagent 一覧（パスと「いつ使うか」）
よく使う npm スクリプト
ユーザー承認が必要な操作の一覧

書かないこと:

長い執筆手順（→ qiita-blog-writing Skill）
常時効かせたい禁止（→ Rule）
機械的ブロックの実装（→ Hook）

Cursor 公式も入口は AGENTS.md（プロジェクトルート／サブディレクトリのネスト可）です。Kaggle 側でも同じファイル名で、コンペ型ごとの Skill 読み分けを書いています（0010）。「入口 MD = 索引」 という役割は共通です。

スリム化ループ — 大量 Skills から整理する手順

Skill を一気に作ったあと、私は次のループで整理しています。

増やす：エージェントに Skill 案を聞き、提案が枯れるまで追加
逃がす：広い検索・大量読取は Subagent へ
分割する：1 Skill が太ったら reference.md やサブ Skill に切る
1箇所にまとめる：重複する禁止・ゲートは Rule、索引は AGENTS.md
捨てる：使い捨て大会用は使い捨てSkills の通り、終わったら削除

「全部 Skill に書く」より、「Skill は手順、Rule はリマインド、Subagent は探索、Hook は強制、AGENTS.md は地図」の方が、あとから diff も読みやすくなりました。

このリポジトリでの実例

blog/
├── AGENTS.md                          # 入口（Skill 一覧・よくあるタスク）
├── .cursor/
│   ├── skills/
│   │   ├── qiita-blog-writing/       # Phase 1〜7 の執筆フロー
│   │   ├── qiita-cli/                # 投稿・記法・検証
│   │   ├── qiita-cross-reference/    # 内部リンク手順
│   │   └── cursor-agent-tooling/     # 本記事の題材（メタ Skill）
│   ├── agents/
│   │   └── cross-reference-researcher.md
│   └── rules/
│       ├── qiita-publish-gate.mdc    # drafts/ と promote のゲート
│       └── cursor-config-hygiene.mdc # 絶対パス・秘匿の禁止
└── scripts/hooks/pre-commit          # Git hook（秘匿の機械ブロック）

※ Cursor Hooks 用の .cursor/hooks.json は、このツリーには含めていません（本リポは git hook 側を採用）。

執筆セッションでは、親エージェントが qiita-blog-writing を読み、関連記事が多そうなら cross-reference-researcher に任せ、投稿しそうになったら Rule と Git hook がブレーキをかける、という流れです。

意識していること

Claude Academy を土台にする（独自格式より、広がっている標準に乗る）
Skill はエージェントに聞いて増やす（提案が出なくなるまででよい）
コンテキストを見て Subagent に逃がす（親チャットは判断と確認に集中）
重複は Rule / AGENTS.md に1箇所（Skill 本文に同じ注意を何度も書かない）
Hook は Cursor Hooks と git hook を分けて考える（本リポ例は git）
メタ Skill は disable-model-invocation を検討（設定改修用が毎回自動起動しないようにする）

まとめ

Cursor でエージェント運用を続けると、Skills・Subagents・Rules・Hooks・AGENTS.md の 5レイヤー をどう分けるかが本体になります。設計の出発点は Claude Academy — Introduction to Agent Skills でよく、Skill はエージェントに「あったら便利な Skill」を聞いて増やし、重くなった探索は Subagent に逃がし、同じ注意書きは Rule など 1箇所にまとめてスリム化 する — このループがいちばんラクでした ((_๑òωó)_ﾊﾞﾝ

関連: 執筆環境と Skill の線引き · Kaggle Skill 分離と Subagent · 使い捨てSkills