0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@Kazeneko

CursorのSkills・Rules・Hooks・Subagents・AGENTS.mdをどう分けるか — Claude Academy通りに育ててスリム化した話

0
Posted at

はじめに

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/ 前提です。

参考リンク:

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 を一気に作ったあと、私は次のループで整理しています。

  1. 増やす：エージェントに Skill 案を聞き、提案が枯れるまで追加
  2. 逃がす：広い検索・大量読取は Subagent へ
  3. 分割する：1 Skill が太ったら reference.md やサブ Skill に切る
  4. 1箇所にまとめる：重複する禁止・ゲートは Rule、索引は AGENTS.md
  5. 捨てる：使い捨て大会用は 使い捨て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

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?