Agent Skillsをどう改善する？実務のフィードバックからSkillを育てる方法

Agent Skillsを作って実際の仕事で使うと、想定していなかった修正が出てきます。そのたびに注意事項を追加するとSKILL.mdが長くなりますが、何も反映しなければ、次の仕事でも同じ手戻りが起こります。

Skillの改善には、実際の仕事で直した内容を使ってください。ただし、個別の指摘をそのまま追加するのではなく、似た修正の共通原因を見つけ、既存の手順や判断基準を直してください。

明らかな手順ミスや必須条件の抜けは、その場で修正できます。一方、「文章が長い」「レビューの指摘が多い」といった判断を伴う問題は、一度の事例で恒久的なルールにしない方がよい場合があります。対象が変われば、必要な説明や指摘の量も変わるからです。

この記事では、記事レビューSkillを例に、改善材料の見つけ方、Skillへ反映する判断、AIに改善作業を手伝わせる方法を説明しています。専用の管理表や複雑な評価環境を前提にせず、普段の仕事を進めながらSkillを育てる方法です。

SKILL.mdの基本構造や作成手順は、Agent Skills（SKILL.md）の作り方ガイドで説明しています。Skill化する仕事の選び方は、Agent Skillsはどんな仕事に使える？Skill化しやすい仕事と、作り込みが必要な仕事を読んでください。Skillを分ける判断は、Agent Skillsはどこまで分けるべき？Skillの粒度と分割タイミングで説明しています。

この記事のまとめ

• 初版Skillは完成形ではなく、実際の仕事で使って育てる
• 成果物の修正と、AIが迷った箇所や不要だった作業を改善材料にする
• 明らかな誤りはすぐ直し、判断を伴う問題は別の仕事でも続くかを見る
• 個別の注意事項を増やさず、似た修正の共通原因から既存ルールを書き換える
• 改善には、削除、references/への移動、script化、Skill分割も含まれる
• Skill改善を独立した重い業務にせず、実際の仕事を進めながら必要な箇所だけ直す
• AIには整理、修正案、再実行を任せ、人が仕事の評価基準と変更の採否を決める

1. Skillは、実際の仕事で使ってから改善点が見える

判断を伴う仕事では、実際にSkillを使わないと、足りない観点や不要な手順をすべて把握できません。まず1件の仕事で使える初版を作り、実務で出た修正をSkillに反映してください。

Agent Skills公式のBest practices for skill creatorsでも、実際の仕事からSkillを作り、実行結果を見ながら改善する考え方が示されています。最初から考えられるルールをすべて書くのではなく、AIが実際にどのように作業したかを見て、不足や過剰な指示を直していく方法です。

記事レビューSkillを例に考えてみましょう。 初版に次の手順を入れたとします。

1. 誤字脱字を確認する
2. 長い文章を見つける
3. 見出しと本文の対応を確認する
4. SEOの観点から不足を確認する
5. 問題と改善案をまとめる

一見すると必要な作業はそろっています。しかし、実際の記事をレビューすると、問題のない表現まで細かく指摘したり、表記の問題を優先して読者の理解に関わる問題を見落としたりすることがあります。編集者や上司が重視する観点が入っておらず、AIによるレビューを終えた後も、編集者や上司から大きな修正を求められる場合があります。

Skillに入れた確認順や判断基準が、実際の仕事で求められているレビューと合っていないことも原因です。

初版を作るときに、過去の成果物や修正履歴をAIへ渡すことは有効です。ただし、それだけで完成とは考えず、実際の案件を1件進めてください。使って初めて、資料を読むタイミング、確認が重複している工程、AIが判断できない箇所が見えてきます。

上司や詳しい人のレビュー観点をSkillに反映する

記事レビューSkillを改善する場合は、上司、編集者、SEO担当者など、その仕事に詳しい人が実際に直した内容を確認してください。

たとえば上司が、毎回「記事を読んだ後に何をすればよいか分からない」と指摘しているなら、レビューSkillに「読者の次の行動が分かるか」という観点が不足しています。上司が記事ごとに同じ指摘を繰り返すのではなく、レビュー工程でこの観点を確認できるようにしてください。

この観点を入れるメリットは、記事の品質を上げることだけではありません。AIによる初回レビューで上司の観点を確認できれば、その後の上司レビューで同じ指摘が戻りにくくなります。 実際にレビューする人の判断基準をSkillへ入れることは、品質向上と手戻り削減の両方につながります。

ただし、上司の発言をすべてそのままルールにする必要はありません。特定の記事だけに必要な指摘なのか、別の記事でも使う判断基準なのかを分けます。

2. 成果物の修正と、AIが迷った箇所を改善材料にする

Skillの改善材料は、完成した成果物の間違いだけではありません。人が直した箇所、AIが途中で迷った箇所、不要だった作業、うまくいった判断も確認してください。

成果物だけを見ると、「文章を直した」「指摘を削った」という結果は分かります。しかし、なぜその問題が起きたかまでは分からないことがあります。Skillを直すには、成果物と作業の進め方を合わせて見る必要があります。

AIの詳しい作業記録が残らない環境もあります。その場合は、成果物と修正コメントをAIへ渡し、考えられる原因と見直すべき手順の候補を整理させてください。記録で確認できない内容は推測として扱い、実際のルール変更は修正理由を確認してから判断してください。参照する資料が分からず質問された、同じ作業をやり直した、不要なファイルを読んだといった事実が分かれば、改善箇所を絞れます。

意図したレビューができた実行からも、改善材料を得られます。どの指示や資料が役立ったかを確認してください。うまくいった手順を残すことも、Skill改善の一部です。

改善メモは3点だけ残す

改善材料を集めるために、専用の管理表を作る必要はありません。 実際に成果物を直したとき、次の3点が分かるように数行残してください。

出てきた内容：表記の細かな指摘が多く、論理の飛躍を見落とした
直した内容：重要な指摘を先にし、表記は最後にまとめた
直した理由：読者の理解に影響する問題を優先するため

修正前と修正後の成果物があるなら、AIへ比較させることもできます。「変更点を列挙してください」とだけ依頼すると、単なる差分一覧になる可能性があります。次のSkill改善に使えるように、「何を直したか」に加えて「なぜ直したか」「別の仕事でも起こりそうか」を整理させてください。

修正理由が分からない場合は、無理にAIへ推測させず、実際に直した人へ確認してください。特に、編集方針、顧客への配慮、社内で重視する判断などは、成果物の差分だけでは分からないことがあります。

3. すぐ直す問題と、何件か見てから直す問題を分ける

再発させる意味がない明らかな誤りは、見つけたときに直してください。一方、対象によって評価が変わる問題は、一度の指摘だけで恒久的なルールにせず、別の仕事でも同じ傾向が出るかを確認してください。

すべての指摘をすぐSKILL.mdへ追加すると、特定の案件にしか当てはまらないルールが増えます。ルール同士がぶつかり、AIが何を優先すべきか分からなくなることもあります。

左側は、もう一度起きても利点がない問題です。正しい参照先に直す、抜けていた工程を追加する、古い指示を削るといった変更をその場で行えます。

右側は、記事の目的や読者によって判断が変わります。専門的な内容なら長い説明が必要な場合があります。公開前の厳格なレビューなら、指摘が多くても問題とは限りません。「文章は短くする」「指摘は5件まで」のようなルールを一度の事例から追加すると、別の記事で必要な内容まで削られる可能性があります。

「3回同じ問題が出たら反映する」といった固定回数も必要ありません。必須条件の抜けなら1回でも直すべきです。主観を伴う問題なら、回数だけでなく、別の案件でも同じ原因から起きているかを確認してください。

好みと仕事の判断基準を分ける

人の修正であっても、すべてがSkillへ入れるべきルールとは限りません。

ある担当者が「この表現は好みではない」と直しただけなら、ほかの担当者や媒体には当てはまらない可能性があります。一方、媒体全体で使わない表現だと確認できた場合は、媒体ルールとしてreferences/へ入れられます。

判断に迷ったら、「この修正を入れなかった場合、仕事として問題になるか」「別の案件でも同じ人が同じ理由で直すか」を確認してください。単なる好みではなく、完成条件やレビュー基準に関係しているなら、Skill改善の候補になります。

4. 個別の指摘を増やさず、共通する原因からSkillを直す

似た修正が続いたら、指摘された表現をそのままルールにせず、なぜ同じ種類の問題が起きたかを探してください。原因に近い手順や判断基準を書き換えると、例外ルールを増やさずに改善できます。

改善の基本は、次の流れです。

1. 実際に直した箇所を並べる
2. 同じ種類の修正をまとめる
3. 共通する原因を考える
4. 原因に関係する既存の手順や判断基準を直す
5. 同じ仕事か、条件の似た仕事で再実行する

重要度の低いレビュー指摘が多い場合

記事レビューSkillを使うたびに、言い回しや表記の細かな指摘が大量に出る一方、読者が理解できない説明や結論の不足を見落としていたとします。

ここで「指摘を増やしすぎない」「重要な問題を見落とさない」という注意を末尾に追加しても、AIは何を重要と考えればよいか分かりません。

修正内容を確認すると、表記や文章形式を最初に確認し、読者への影響を後から見ていることが共通原因かもしれません。その場合は、注意事項を足すのではなく、レビュー順を次のように書き換えてください。

1. 読者の疑問に答え、次に何をすればよいか分かるか
2. 主張と根拠がつながり、理解に必要な前提が抜けていないか
3. 編集者や上司が重視する観点を満たすか
4. 見出し、文章、表記の問題を確認する

確認の優先順位を変えれば、細かな指摘を禁止せず、重要な問題を先に扱えます。

「導入が長い」という修正が続く場合

「導入は300文字以内」「背景は2段落まで」というルールを追加すると、読者へ前提を説明する必要がある記事まで短くなります。

複数の記事で「導入が長い」「前提説明が多い」「結論まで遠い」と直されているなら、共通原因は文字数ではなく、読者が必要としているかを確認せずに背景を追加していることかもしれません。

その場合は、「導入には何文字使うか」ではなく、「読者の疑問と記事で得られる答えを先に示し、理解に必要な前提だけを残す」という判断基準へ直してください。

箇条書きが多く、話のつながりが分からない場合

「箇条書きを使わない」と禁止すると、手順や比較まで長い文章になります。問題は箇条書きそのものではなく、理由や因果関係を説明すべき内容まで、短い項目へ分解していることです。

「比較、選択肢、短い手順は箇条書きを使い、理由、背景、因果関係は文章で説明する」と使い分けを示せば、読みやすさを保ちながら必要な箇条書きを使えます。

共通原因の候補は、AIに挙げてもらえます。ただし、AIが挙げた原因に根拠があるとは限りません。過去のレビューや、実際に修正した人の意図と照らしてください。

5. Skillの改善は、SKILL.mdへの追記だけではない

改善点が見つかったときは、まず既存ルールを書き換えられないか確認してください。改善には、追記だけでなく、重複の統合、不要な指示の削除、references/への移動、script化、Skill分割も含まれます。

注意事項を末尾に足し続けると、古いルールと新しいルールが離れた場所に残ります。AIが両方を読み、どちらを優先すべきか迷う状態になります。新しい指摘を加える前に、同じ目的のルールがすでにないかを確認してください。

詳しいレビュー観点はreferences/へ移す

編集者や上司のレビュー観点が増えると、SKILL.mdが確認項目だけで埋まることがあります。その場合は、詳しい観点をreferences/review-points.mdへ移し、SKILL.mdには読むタイミングを残してください。

記事の内容レビューを始める前に、references/review-points.mdを読み、
媒体の方針と編集者・上司が重視する観点を確認してください。

ファイルを移すだけでは、AIが必要なときに読むとは限りません。 何をする前に、どのファイルを読むかまでSKILL.mdに書いてください。

決まった検査はscripts/へ移す

リンク切れ、見出し階層、必須項目、画像ファイルの有無など、条件どおりに確認できる処理はscript化できます。 毎回同じ検査方法をAIに考えさせず、検査結果を受けてAIが記事を直し、再検査する流れにできます。

scriptを使う場面と作り方は、Agent Skillsでscriptsを使う方法｜使う場面・作り方・使い方で説明しています。

モードや分岐が増えたらSkill分割を検討する

記事の内容レビューと、公開前のリンク・画像・表記検査では、手順と完成条件が異なります。 それぞれを単独で頼む機会が増えたなら、別Skillにする候補です。

ただし、最初から細かく分ける必要はありません。まず1つの工程として使い、モードや分岐が増えた部分だけを分けてください。詳しい判断方法は、Agent Skillsはどこまで分けるべき？Skillの粒度と分割タイミングで説明しています。

6. AIに改善案を作らせ、同じ仕事で確かめる

現在のSkillと実際の修正内容をAIへ渡せば、修正の整理、共通原因の候補、Skillの変更案、再実行まで依頼できます。注意事項を増やすのではなく、既存ルールを最小限の変更で直すように指定してください。

AIへ渡すのは、次の内容です。

• 現在のSKILL.mdと、今回の仕事で使ったreferences/
• Skillを使って作った成果物
• 人が直した後の成果物、またはレビューコメント
• AIが迷った箇所や、やり直した作業が分かればその内容

すべての過去案件を集める必要はありません。まずは今回使ったSkillと、今回の修正前後から始めてください。似た修正が続いたら、ほかの案件の修正前後もAIへ渡してください。

AIへは、次のように依頼できます。

このSkillを実際の仕事で使い、成果物を修正しました。
現在のSkill、修正前後の成果物、レビューコメントを比較してください。

1. 何が修正されたか
2. なぜ修正されたか
3. 別の仕事でも起こりそうか
4. Skillのどの手順や判断基準が原因か

を整理してください。

個別の注意事項を増やすのではなく、既存ルールの書き換えで
直せるかを先に確認してください。不要なルールの削除、
referencesへの移動、script化、Skill分割が必要な場合は、
その理由も示してください。

変更後は、同じ条件の仕事でSkillを実行し、以前の問題が減ったか、
別の問題が増えていないかを確認してください。

修正案だけで終わらず、もう一度使う

Skillの文章が分かりやすくなっただけでは、改善できたとは判断できません。 修正後のSkillを、同じ成果物、または条件の近い成果物で使ってください。

記事レビューSkillなら、以前のレビュー結果と比べながら、次の点を確認してください。

• 重要度の低い指摘だけが減ったか
• 読者の理解に関わる問題を見つけられたか
• 編集者や上司の観点が反映されたか
• 必要な指摘まで消えていないか
• AIが必要なreferences/やscripts/を使ったか

以前の問題が減っても、必要な指摘まで出なくなったなら改善とはいえません。「細かな指摘が多い」という問題に対して、指摘数を制限するだけでは、この状態が起きます。 問題を減らすだけでなく、仕事の目的を満たしたかを確認してください。

通常のエラー修正や再実行はAIへ依頼できます。人が毎回、途中のエラーを手作業で直す必要はありません。ただし、公開、削除、外部システムの更新など、元に戻しにくい操作が含まれる場合は、その操作前に確認するようSkillへ入れてください。

7. Skill改善を重い運用にしない

個人利用や小規模な業務では、Skill改善を独立した大きな業務にせず、実際の仕事の中で必要な部分だけ直してください。Skillは仕事を進めるために使うものであり、Skillを管理すること自体が目的ではありません。

すべての実行ログを残し、指摘を分類し、評価点を付け、定期的な見直し会議まで始めると、管理自体に時間を取られます。実際の仕事が進まなければ、Skillを使う意味が薄くなります。

個人利用や小規模な業務では、まず次の4段階から始めてください。

1. 実際の仕事でSkillを使う
2. 成果物を直したら、修正内容と理由を数行残す
3. 同じ問題が続いたら、AIへ共通原因と修正案を出させる
4. Skillを直し、同じ仕事か似た仕事で再実行する

記事レビューSkillなら、毎回の指摘数や記事の評価点を記録する必要はありません。「表記の指摘を減らし、読者の理解に関わる問題を先に確認するよう変更した」のように、実際に変更した判断基準と、その理由だけを残してください。

固定した見直し日も必要ありません。明らかな間違いはその場で直し、それ以外は修正理由を残してください。同じ傾向が続いたとき、改善メモが数件たまったとき、SKILL.mdが読みにくくなったときにまとめて整理してください。

Skill改善に時間をかけすぎているサイン

次のような状態になったら、記録や見直しの方法を簡略化してください。

• Skillを使うたびに、成果物より先にSKILL.md全体を見直している
• 実際には使わない評価項目や管理欄が増えている
• 一度しか起きていない問題のために、多数の例外ルールを作っている
• 改善記録を残す作業が、成果物を確認する時間より長い
• Skillを直しているが、修正後のSkillを実際の仕事で使っていない

特に最後の状態には注意が必要です。Skillの文章だけを何度直しても、実際の仕事で使わなければ、良くなったか分かりません。 改善案を増やすより、1件の仕事で使い、実際に必要だと確認できた変更だけをSkillに反映してください。

8. AIにSkillの評価と改善を任せきりにしない

AIには、修正内容の整理、共通原因の候補、Skillの変更案、再実行を任せられます。ただし、何をよい成果とするか、どの観点を優先するか、変更を正式に採用するかは人が決めてください。

AIは、与えられた評価基準に沿って成果物を確認できます。しかし、その評価基準が実際の仕事に合っているかは、AIだけでは決められません。

記事レビューなら、「誤字脱字がない」「見出し階層が正しい」といった確認だけで、よい記事とは判断できません。誰に何を伝える記事なのか、媒体が何を重視しているか、編集者や上司が、どの状態なら公開できると判断するかによって、判断が変わります。

評価基準が足りないままAIに改善を任せると、AIが確認しやすい項目ばかり増える可能性があります。たとえば、文字数、指摘数、必須語句の有無は数えやすい一方、読者が納得できるか、重要な疑問へ答えているか、独自の知見があるかは、単純な数値では決まりません。

AIが自分で作った成果物を評価すると、問題を見落としたり、自分の成果物を高く評価したりすることがあります。評価役を別のAIにしても、実務に合う評価基準がなければ、妥当な変更かどうかは決められません。

AIへ任せる作業と、人が決めることを分ける

人がAIの作業をすべて管理する必要はありません。 修正前後の比較、原因候補の整理、Skillの修正、再実行はAIへ任せられます。人は仕事の目的と判断基準を示し、変更を採用するか決めてください。

専用の評価環境を作る前に、少数の確認用事例から始める

Skillを直すたびに、専用の評価環境を用意する必要はありません。 個人利用や小規模な運用なら、以前に問題が出た成果物と、条件の少し違う成果物で再実行し、修正前より良くなったかを確認してください。

複数人へ配布する場合も、すぐに評価システムを作る必要はありません。組織へ本番展開するSkillを対象としたClaude Platformの企業向けSkillガイドでは、Skillを起動すべき依頼、起動すべきでない依頼、判断しにくい依頼を含む3〜5件の代表例を用意する方法が示されています。 まず必要なのは、大きな仕組みではなく、実際の利用場面を表す確認用事例です。

次のような状態では、専用の評価環境を検討してください。

• 本番で利用するSkillの変更が、多数の成果物や利用者へ影響する
• Skillや利用するAIを頻繁に変更し、以前は成功していた仕事に失敗していないか継続的に確認したい
• 複数のSkillを同時に使い、誤ったSkillの起動やSkill同士の干渉を確認する必要がある
• 実行ごとに結果が変わり、1回の再実行だけでは改善したか判断できない

また、法務、金額、権限、公開、削除など、失敗時の影響が大きい仕事では、評価環境を作っても、その操作をAIへすべて任せてよいとは限りません。人の承認、操作できる範囲の制限、元へ戻す方法を別に用意してください。OpenAIのAIエージェント構築ガイドでも、取り消せない操作や影響の大きい操作には、人が介入する仕組みを設けることが案内されています。

リンク切れ、必須項目、見出し階層のように機械的に合否を決められる項目は、まずscriptへ入れ、普段のSkill実行時に確認してください。 これらの項目だけを確認するために、専用の評価環境から始める必要はありません。

まとめ：個別の修正ではなく、仕事の判断基準をSkillに反映する

Agent Skillsの改善は、注意事項を増やし続ける作業ではありません。 実際の仕事で何が直され、AIがどこで迷ったかを確認し、同じ問題が起きる原因を踏まえ、Skillの手順や判断基準を修正する作業です。

まず1件の仕事でSkillを使い、成果物を直したら、「何が出たか」「どう直したか」「なぜ直したか」を数行残してください。明らかな誤りはその場で直し、判断を伴う問題は、別の仕事でも同じ原因から起きているかを確認してください。

似た修正が続いたら、個別の禁止事項を増やさず、共通原因から既存ルールを書き換えてください。不要な指示は削り、詳しい観点はreferences/へ移し、毎回同じ機械処理はscripts/へ移せます。モードや分岐が増えた場合は、Skillの分割も検討できます。

改善運用を重くする必要はありません。 Skillを直すことだけに時間を使わず、実際の仕事を進めながら、次の仕事でも役立つ判断基準だけをSkillに反映してください。

AIには、修正内容の整理、共通原因の候補、Skillの修正案、再実行を任せられます。一方、仕事で何を重視するか、どの変更を採用するかは人が決めます。

Skillを育てることは、AIへの指示を増やすことではありません。自分や組織が実務で使っている判断基準を、次の仕事でも使える形にすることです。

参考資料

• Best practices for skill creators（Agent Skills公式）
• Skill authoring best practices（Claude Platform Docs）
• Harness design for long-running application development（Anthropic）
• Skills for enterprise（Claude Platform Docs）
• A practical guide to building AI agents（OpenAI）