Writing/AIエージェントの「スキル」って何？ — 仕組みとフォルダ構成をメモした
AIエージェントの「スキル」って何？ — 仕組みとフォルダ構成をメモした
Cursor と Claude Code で使う Skills の入門。スキルクリエイター、読み込みの流れ、フォルダ構成を初心者向けに整理。
2026.05.24·実験記録·AI · Claude · 個人開発 · 学習ログ
XでシェアCursor や Claude Code を使っていると「スキル」という言葉をよく見かけます。
結論から言うと、スキルは「AIに渡す専用の手順書フォルダ」です。 毎回同じ説明をチャットで繰り返す代わりに、Markdown でルールを置いておき、記事執筆やコミット作法など「決まった仕事」のときだけ読ませます。
この記事では、Cursor と Claude Code for VS Code で共通して使える Skills の考え方と、スキルクリエイター（作り方のガイド）で決まっているフォルダ構成を、自分用メモとしてまとめます。
スキルって何？
ざっくり言うと、特定の作業のやり方を書いた Markdown パッケージです。
- プロンプト1回分 … その場限り。会話が変わると消える
- ルールファイル … プロジェクト全体に常時効く（例:
.cursor/rules/*.mdc） - スキル … 「この種類の仕事のときだけ」詳しい手順を読む
スキルは 「いつ使うか」 が description に書いてあり、エージェントが「記事を書く」「PDFを処理する」などの場面で自分から選びやすくなっています。
スキルは AI の頭の中に常駐する知識ではありません。必要になったタイミングで SKILL.md を開いて読む 仕組みです。そのぶん、本文は短く、詳細は別ファイルに逃がすのが基本です。
どう読み込まれる？（3段階）
スキルはだいたい 3段階 でコンテキストに入ります。
- メタデータ …
nameとdescriptionだけが先に見える（「何のスキルか」の名札） - SKILL.md 本文 … スキルが選ばれたときに読む手順・チェックリスト
- references / scripts … 必要なときだけ。長い表やテンプレ、検証用スクリプト
これを 段階的開示（プログレッシブ・ディスクロージャ） と呼びます。 全部を一度に載せると会話が重くなるので、「まず SKILL.md、足りなければ reference」が鉄則です。
MDX では <Image src="/images/..." alt="説明" /> で図を入れられます。public/images/ に PNG や WebP を置けば OK です。図解は ChatGPT や Nanobanana などで作った画像をそのまま使えます（ファイル名は日付＋内容が分かる英数字推奨）。
フォルダ構成（最小セット）
スキルは フォルダ1つ＝スキル1つ です。中身の必須は SKILL.md だけ。
skill-name/
├── SKILL.md # 必須。手順の本体
├── references/ # 任意。長い資料・テンプレ
│ └── templates.md
├── scripts/ # 任意。毎回同じ Python など
│ └── validate.py
└── assets/ # 任意。画像・雛形（読まずにコピーする用）SKILL.md の書き方
先頭に YAML frontmatter を付けます。
---
name: my-skill-name
description: 何をするスキルか。いつ使うか（英語でも日本語でも、トリガー語を入れる）
---description はかなり重要です。
「PDF」「コミット」「MDX」など、ユーザーが口にしそうな単語 を入れると、エージェントがスキルを選びやすくなります。
本文は 命令形・短文 が向いています（「〜してください」より「〜する」）。
~/.cursor/skills-cursor/ は Cursor 組み込み用です。自分のスキルは作らないでください。
置き場所は2種類
| 種類 | パス例 | 誰が使えるか |
|---|---|---|
| プロジェクト | リポジトリ内 .cursor/skills/ または .claude/skills/ | そのリポジトリを開いた人全員 |
| 個人 | ~/.cursor/skills/ | 自分のマシン上の全プロジェクト |
同じリポジトリで Cursor と Claude Code の両方を使うときは、中身を揃えたいので、私は .cursor/skills/ に作って .claude/skills/ にコピー しています（中身は同一でOK）。
スキルクリエイターとは
スキルクリエイター は、スキルを設計・作成するときの「作法集」です。
Cursor には /create-skill、Claude には skill-creator スキルとして入っていることが多いです。
やっていることはシンプルです。
- 用途を具体例で決める … 「メモから MDX」「PR レビュー」など
- SKILL.md に書く内容と、references に逃がす内容を分ける
- フォルダを作る … テンプレ生成スクリプト
init_skill.pyがある環境もある - 実タスクで試す … うまくいかない部分だけ SKILL.md を直す
スキルクリエイターの鉄則は 「エージェントはもともと賢い。本当に必要な手順だけ書く」 です。一般論の長文はトークンの無駄になりやすいです。
ルール・CLAUDE.md との違い（私の整理）
eighgent では、次のように役割を分けています。
| ファイル | 役割 |
|---|---|
WRITING_STYLE.md | 人間も読める文体の正 |
.cursor/rules/content.mdc | content/**/*.mdx を触ったとき 自動 で効く入口 |
.claude/CLAUDE.md | Claude Code 起動時に読むプロジェクト全体の指示 |
.cursor/skills/eighgent-content/ | 記事生成・編集の 手順書スキル |
ルールは「このファイルを開いたら必ず」、スキルは「記事を書く仕事のときに詳しく」というイメージです。
実際のフォルダはこんな感じです。
eighgent/
├── WRITING_STYLE.md
├── .cursor/
│ ├── rules/content.mdc
│ └── skills/eighgent-content/
│ ├── SKILL.md
│ └── references/
│ ├── frontmatter-and-paths.md
│ └── mdx-checklist.md
└── .claude/
├── CLAUDE.md
└── skills/eighgent-content/ # Cursor 側と同内容チャットで @eighgent-content と呼ぶか、「eighgent の記事を書いて」と言えば、上の手順に沿って WRITING_STYLE.md まで読みに行きます。
自分用スキルを1つ作るなら
最初の1個は、いちばん繰り返している説明 がおすすめです。
- コミットメッセージの型
- このサイトの MDX の frontmatter
- 社内 API の呼び方
手順の型は次のとおりです。
my-skillフォルダを作るSKILL.mdに frontmatter ＋ 5〜10 行の手順- 長いテンプレは
references/へ - 実際のタスクで1回動かし、足りない行だけ追記
スキルに「2025年8月までは旧API」と書くような 期限付きの話 は入れない方がいいです。古くなったまま残りやすいです。
まとめ
- スキル … 決まった仕事用の手順書フォルダ。必須は
SKILL.mdだけ - 読み込み … 名札 → 本文 → reference / script の順で必要な分だけ
- 置き場所 … プロジェクト共有は
.cursor/skills/と.claude/skills/、個人用は~/.cursor/skills/ - スキルクリエイター … 作り方のベストプラクティス。短く、具体例とトリガー語を書く
次にやるなら、自分が毎回コピペしている説明を1つ選び、SKILL.md に移してみてください。
うまくいけば、チャットがだいぶ短くなります。
作ったスキルは /lab にメモしておくと、後から見返せます。