VPS Notes
VPS

Claude Code のスキルの作り方: SKILL.md の書き方と、常駐エージェントの手順書を移して分かった本当の違い

Claude Code のスキル (SKILL.md) の置き場所、frontmatter、呼ばれる仕組みを公式ドキュメントで整理し、VPS の常駐エージェントの手順書 3 つを移して前後を比べました。選ばれる精度とコストはほぼ同じ。差が出たのは「会話の途中で増えたスキル」でした。

claude-codeskillsai-agentxserver-vps

本記事にはプロモーション (アフィリエイト広告) が含まれます。

「Claude Code のスキルとは何か」「どう作るのか」で調べている人向けに、先に結論を置きます。

スキルは .claude/skills/<名前>/SKILL.md に置く手順書です。 先頭の description だけが毎回読まれ、本文は使うときに読まれます。Claude は description を見て、どのスキルを使うかを自分で選びます。/名前 で自分から呼ぶこともできます。

この記事で足したいのは、その先の実測です。私は VPS に常駐させた Claude Code のエージェント に、独自の手順書 (skills/*.md と、その索引を CLAUDE.md から読む仕組み) を持たせていました。これを公式のスキルに移して、前後を比べました。

常駐させるエージェントは、会話を何日も続けます。その間に週次の見直しが手順書を足します。スキルに移す価値は、ここにありました。

この記事で使う環境

XServer VPS クラウド
4GB (4 コア) で月 2,480 円〜。スキルを持たせた常駐エージェントを動かしている VPS です。
公式サイトを見る

スキルとは: CLAUDE.md との違い

公式ドキュメント (Skills、2026-09-26 確認) をもとに整理します。

CLAUDE.md スキル
置き場所 プロジェクトの直下など .claude/skills/<名前>/SKILL.md
いつ読まれるか 会話の始まりに全文 description は会話の始まりに。本文は使うときだけ
何を書くか いつも守ること (役割、ルール) 特定の作業の手順
呼び方 呼ばない (常に効いている) Claude が選ぶ。/名前 でも呼べる
途中の変更 会話の途中で書き換えても、その会話には効かない 同じ会話のうちに反映される

CLAUDE.md に手順を全部書くと、関係のない作業のときも毎回読まれます。スキルに分ければ、普段は description の 1〜2 行だけで済みます。

最後の行が、この記事の実験で効いてきます。公式ドキュメントには、スキルのフォルダを監視していて、追加・編集・削除を会話の途中でも拾う、と書かれています。

置き場所

種類 場所 使える範囲
個人 ~/.claude/skills/<名前>/SKILL.md そのマシンの全プロジェクト
プロジェクト .claude/skills/<名前>/SKILL.md そのリポジトリ
サブフォルダ <サブフォルダ>/.claude/skills/<名前>/SKILL.md そのフォルダの中で作業したとき

ほかに、組織で配るもの、プラグインに入っているもの、claude.ai のアカウントで有効にしたもの (同期される) があります。

SKILL.md の書き方

iris のスキルの 1 つです。先頭の --- で囲んだ部分 (frontmatter) に name と description を書き、その下が本文です。

---
name: server-health
description: サーバー (vpsnotes-001) の健康状態を確認する。ディスクの空き、メモリ、失敗した systemd ユニット、SSH のログイン失敗を一度に見る。「調子どう?」「サーバー大丈夫?」「朝のチェック」と言われたとき、定時のチェックのときに使う。
---

# server-health: サーバーの健康状態を確認する

## 目的
ディスク・メモリ・失敗した systemd ユニット・SSH のログイン失敗を一度に見る。

## 手順
(コマンド)

## つまずいた点
(過去に間違えたこと)

## 確認方法
(何が出れば「異常なし」か)

description が一番大事です。 Claude はこれを見て、スキルを使うかどうかを決めます。「何をするか」に加えて、「どう言われたときに使うか」を、実際に言いそうな言葉で書きます。公式ドキュメントも、スキルが呼ばれないときは、まず description に呼ばれるきっかけの言葉があるかを確かめるよう書いています。

name を省くとフォルダ名が名前になり、/server-health で呼べます。本文の形は自由です。iris では「目的 / 手順 / つまずいた点 / 確認方法」の 4 節に決めています (記事 13 のルール 4)。

frontmatter の主な項目

ほかにも項目があります。公式ドキュメントから、使いどころのあるものを抜き出しました。この記事の実験で使ったのは name と description だけです。

項目 何をするか
when_to_use 使う場面の補足。description の後ろに足される
disable-model-invocation: true Claude が自分では呼ばない。/名前 でだけ動く。デプロイなど、勝手に動くと困るもの向け
user-invocable: false / のメニューに出さない。Claude だけが使う背景知識向け
allowed-tools そのスキルの間だけ、確認なしで使えるツールを決める
arguments /名前 引数 の引数に名前を付けて、本文の $名前 に入れる
context: fork 今の会話とは別のサブエージェントで動かす

本文には、!`コマンド` と書くと、Claude が読む前にコマンドを実行して、結果に置き換える機能もあります。

iris の手順書をスキルに移す

移す前の iris は、手順書を skills/<名前>.md に置き、その索引 skills/INDEX.md を CLAUDE.md から @import で読んでいました。索引は「いつ使うか — ファイル」を 1 行ずつ並べたものです。

iris/
├── CLAUDE.md          (@skills/INDEX.md を読む)
└── skills/
    ├── INDEX.md
    ├── server-health.md
    ├── connector-setup.md
    └── gmail-cleanup.md

移した後はこうです。索引はなくなり、その役目は各スキルの description が引き継ぎます。

iris/
├── CLAUDE.md
└── .claude/skills/
    ├── server-health/SKILL.md
    ├── connector-setup/SKILL.md
    └── gmail-cleanup/SKILL.md

やったことは 3 つです。

  1. 手順書の先頭に name と description を足して、.claude/skills/<名前>/SKILL.md に移す。本文はそのまま
  2. CLAUDE.md から @skills/INDEX.md を消す
  3. 「手順を書け」と指示していた箇所 (CLAUDE.md の学習のループと、週次の見直しのスクリプト) の置き場所を、新しい形に直す。「description には、何をするかと、どう言われたときに使うかを書く」と足す

3 を忘れると、iris は次に学んだ手順を古い場所に書きます。手順書を自分で書くエージェントなら、書き方の指示も一緒に移してください。

移す前と後で比べる

同じ 3 つの質問を、移す前と後の iris に claude -p で聞きました。

質問 移す前 移した後
サーバーの調子どう? cat skills/server-health.md で読んで実行 Skill で server-health を呼んで実行
Google カレンダーも使えるようにしたい cat skills/connector-setup.md Skill で connector-setup
楽天のメールが受信トレイにないのはなぜ? cat skills/gmail-cleanup.md Skill で gmail-cleanup

どちらも 3 問とも正しい手順書を選びました。 違うのは、手順書をファイルとして読むか、スキルとして呼ぶかだけです。答えの中身もほぼ同じでした。

コストも比べました。claude -p が出す API 換算の金額です。

質問 移す前 移した後
サーバーの調子 $0.150 (4 ターン) $0.162 (6 ターン)
Google カレンダー $0.146 (3 ターン) $0.157 (5 ターン)
受信トレイにない $0.170 (3 ターン) $0.187 (5 ターン)

移した後の方が 1 割ほど高く出ました。ただし、ターンの差は手順の選び方ではなく、iris が記録のついでに git show を打ったり、過去の notes を探したりしたことによるものです。スキルそのものが増やしたのは、Skill を呼ぶ 1 ターンです。

会話の始まりに読む量も見ました。1 ターン目の新規の読み込みは、移す前が 10,716 トークン、移した後が 10,886 トークンです。3 つのスキルの description で、約 170 トークン増えました。 索引の 3 行を description に置き換えたので、増えたのは description を詳しく書いた分です。

手順書が 3 つなら、索引の方式でも十分に回ります。ここまでなら、移す理由は薄いです。

差が出たのは「会話の途中で増えたスキル」

常駐のエージェントでは、会話が何日も続きます。その間に、週に 1 回の見直し (別のプロセス) が、新しい手順書を足します。常駐側の会話は、それに気づけるでしょうか。

これを再現しました。1 つの会話の中で、次の順に進めます。

  1. 「おはよう」と話しかける (会話が始まり、CLAUDE.md とスキルの一覧が読まれる)
  2. 外から、新しい手順書「どのディレクトリが容量を食っているかを調べる (disk-usage)」を足す。移す前の方式なら skills/disk-usage.md と索引の 1 行を、移した後なら .claude/skills/disk-usage/SKILL.md を置く
  3. 同じ会話のまま「ディスクの容量を食ってるのはどこ?」と聞く

結果は分かれました。

移す前の iris は、新しい手順書に気づきませんでした。 会話の始まりに読んだ索引には、disk-usage がまだないからです。代わりに server-health を読み、自分で du -xh --max-depth=1 / を打ちました。root ではないので読めないフォルダが多く、「df では 21G 使っているのに、du では 13G しか数えられない。約 8G の行き先が分からない」と答えています。

移した後の iris は、同じ会話のまま disk-usage を呼びました。 2 ターン目のスキルの一覧に、disk-usage が増えていました。手順どおりホームと docker に絞って数え、「~/immich-app が 7.5G、docker のイメージが 5.1G、ボリュームが 2.3G」と、行き先まで答えています。

移す前の方式でも、会話を始め直せば新しい索引が読まれます。しかし常駐のエージェントは、会話を始め直す機会がほとんどありません。週次の見直しで育った手順が、再起動までは使われないことになります。

「長く動かすほど賢くなる」エージェントにとって、学んだ手順がすぐ使えるかどうかは本質的な差です。 公式のスキルに移す一番の理由は、ここでした。

スマホのアプリから使う

移した後の iris を再起動して、スマホの Claude アプリから「サーバーの調子どう?」と聞きました。

Claude アプリで iris に「サーバーの調子どう?」と聞くと、ディスクの増加に気づいて原因を調べ、記憶とスキルを更新して報告している

「使用: 1 個のツール」が、server-health のスキルです。iris はこのとき、ディスクが 9/23 の 5.1G から 21G に増えていることに気づき、原因 (Immich の検証の残り) まで追いました。そして自分で、スキルに「前回より大きく増えていたら、どこを見るか」の手順を足し、記憶の古い行も直しています。スキルを使いながら、スキルを育てています。

アプリの入力欄に /server-health と打っても呼べました。

Claude アプリで /server-health と打つと、スキルの手順で確認して結果を返している

決まった確認を毎回同じ手順でやらせたいなら、言葉で頼むより /名前 の方が確実です。

つまずいた点

移行と、前後を比べるテストまで含めて、30 分ほどでした。

次にやること

まとめ

XServer VPS クラウド
スキルを持たせた常駐エージェントを 24 時間動かしている VPS です。
公式サイトを見る