Agent Skillsでscriptsを使う方法｜使う場面・作り方・使い方

Agent Skillsには、仕事の進め方を書くSKILL.mdだけでなく、AIが実行できるコードをscripts/へ含められます。プログラムを書けなくても、どの処理を繰り返したいか、どのような結果が欲しいかをAIへ伝えれば、scriptの作成やSKILL.mdへの組み込みを依頼できます。

scriptにするのは、AIに毎回考え直させる必要がなく、同じ方法で繰り返したい処理です。まずSkillを使い、AIが同じ抽出・変換・検査を繰り返している部分から追加してください。

この記事では、記事レビューSkillを共通の例として使います。記事の主張が伝わるか、説明が不足していないか、読者に役立つかを確認する作業はAIに任せます。一方、文字数、見出し階層、必須項目、画像パスなどは、条件を決めてscriptで検査できます。

scriptを使う場面、AIへの作成依頼、SKILL.mdから使う流れを順番に説明しています。コードやコマンドが分からない場合も、AIへ何を伝え、何を確認すればよいかが分かる内容です。

Skill化する仕事の選び方から確認したい場合は、Agent Skillsはどんな仕事に使える？Skill化しやすい仕事と、作り込みが必要な仕事を先に読んでください。別Skillとscripts/の違いは、Agent Skillsはどこまで分けるべき？Skillの粒度と分割タイミングで説明しています。

この記事のまとめ

• AIが毎回、同じ処理のためにコードや複雑なコマンドを作っているなら、その処理をscriptにする
• 抽出・集計・変換、完成物の検査、複雑な定型操作はscriptにしやすい
• 記事の内容を読んで考える作業はAI、条件どおりに確認する作業はscriptに任せる
• 既存ツールで済む処理は、独自scriptを作らずSKILL.mdから直接使う
• コードが分からない場合は、入力、確認したい条件、欲しい結果をAIへ伝えてscriptを作成してもらう
• AIが作ったscriptは、実際の仕事で試し、間違いや使いにくさを修正してからSkillへ組み込む
• SKILL.mdには、実行する場面と、検査で問題が見つかった後の修正・再実行を書く

1. scriptsは、AIが毎回同じ処理を作り直さないために使う

仕事の手順と判断基準はSKILL.mdに書き、その中で繰り返す決まった処理をscripts/へ置いてください。

Agent Skillsの公式Specificationでは、SKILL.mdを必須ファイルとし、必要に応じてscripts/やreferences/を追加できる構成が示されています。scripts/には、AIに繰り返し実行させるコードを置きます。

ここからは、記事レビューSkillを例に説明します。 記事レビューSkillとは、記事を読み、媒体のルールや編集者の観点から問題を見つけ、改善案を出すSkillです。

記事レビューSkillでは、手順・判断基準・形式検査を次のように分けられます。

たとえば、SKILL.mdへ「見出し構造を確認してください」とだけ書いた場合、AIはその都度、確認方法を考えます。ある回では目で確認し、別の回では一時的なコードを作り、さらに別の回では確認が抜けるかもしれません。

見出しの検査条件が決まっているなら、AIへ検査用scriptの作成を依頼できます。 「H2の次にH4が現れたら問題として報告する」「タイトルが複数あれば報告する」といった条件を一度scriptへ入れれば、その後は同じ方法で確認できます。

一方、「この見出しで読者の疑問に答えられるか」は、見出しの種類だけでは分かりません。記事のテーマ、想定読者、前後の説明を読んで考える必要があります。見出しが読者の疑問に答えているかは、SKILL.mdの手順とreferences/に置いた観点を使ってAIが確認します。scriptは、見出し階層など、あらかじめ決めた形式条件を検査します。

2. scriptにしやすいのは3種類の処理

何を入力し、どのような結果になれば正しいかを決められる処理は、scriptにしやすいものです。 特に、抽出・集計・変換、完成物の検査、複雑な定型操作の3種類から探してください。

必要な情報を同じ方法で取り出す

1つ目は、元のファイルから必要な情報を取り出し、数え、決まった形へ変える処理です。

記事レビューSkillでは、本文の文字数を数える、H2・H3・H4の一覧を作る、記事内のリンクや画像パスを取り出す、といった処理があります。ほかにも、アンケート結果を項目別に集計する、会議の記録から担当者と期限を抜き出す、複数ファイルの名前をそろえる処理などが該当します。

一度しか行わない処理なら、その場でAIへ依頼できます。しかし、Skillを使うたびに同じ抽出方法を考え、似たコードを作っているなら、その処理をscriptへまとめる候補になります。

完成物を、あらかじめ決めた条件で検査する

2つ目は、必須項目、ファイルの有無、見出しの順序など、合否の条件を先に決められる検査です。

記事レビューSkillでは、必須項目がそろっているか、見出し階層が飛んでいないか、指定された画像ファイルが存在するかを確認できます。データ更新のSkillなら、必須列、空欄、重複を検査できます。文書作成のSkillなら、必要なファイルが生成されているか確認できます。

文言チェックも、記事レビュー用scriptへ入れやすい検査です。 使いたくない表現の一覧を用意し、該当する文言と場所をアラートとして表示するようにします。新たに避けたい表現が見つかったときは一覧へ追加できるため、次の記事から同じ条件で確認できます。

検査用scriptは、成果物を作成し、問題を修正する流れに組み込んでください。 AIが検査結果を使って成果物を直してから、作業を終えられます。

成果物を作る
→ scriptで検査する
→ 問題の場所と直し方を確認する
→ AIが成果物を修正する
→ もう一度検査する
→ 問題がなくなったら完了する

Agent Skills公式のBest practices for skill creatorsでも、作業後に検査し、問題があれば修正して再検査する流れが紹介されています。

間違えやすい一連の操作をまとめる

3つ目は、複数の操作を正しい順序で進める必要があり、毎回指示すると間違えやすい処理です。

たとえば、Wordファイルの内部データを取り出し、必要な箇所を変更して元のWord形式へ戻した後、ファイルが壊れていないか確認する作業があります。この一連の操作は順番が決まっているため、共通部分をscriptへまとめられます。Webアプリのテストでも、サーバーの起動、準備の確認、テスト、終了という一連の操作にscriptが使われています。

Anthropicが公開しているdocx Skillでは、Wordファイルの検査などに補助scriptを使っています。webapp-testing Skillでは、サーバーの起動から終了までの共通処理をscriptへまとめています。

このような操作も、AIへscript化を依頼できます。AIが毎回似た操作を行っていると気づいたら、「この一連の操作を繰り返し使えるscriptにしてください」とAIへ依頼してください。AIが作った後、実際のファイルで動かし、途中で止まらないか、必要な結果が得られるかを確認してください。

3. AIとscriptは、確認条件を先に決められるかで使い分ける

記事の内容を読んで考える作業はAIに任せ、条件に沿って同じ結果を出す作業はscriptに任せてください。

記事レビュー全体をscriptにするわけではありません。同じ「確認する」という作業でも、文章の意味を考える必要があるか、確認条件を先に決められるかによって分けます。

script化する処理を探すときは、次の3点を確認してください。

1. AIが実行のたびに、似たコードや長いコマンドを作っているか。
2. 正しい結果と問題のある結果を、例として示せるか。
3. scriptの結果を受けて、AIが修正や次の作業へ進めるか。

たとえば「記事の品質を100点満点で評価する」は、点数で示すため、条件どおりに検査できる処理のように見えます。しかし、点数を付けるには、読者への分かりやすさ、説明の深さ、根拠などを考える必要があります。この作業は、評価観点をreferences/へ書き、AIに理由と改善案を出させる方が適しています。

反対に、「すべての画像パスが実在するか」は、確認条件が明確です。AIが一つずつ確認方法を考えるより、scriptでまとめて調べられます。

scriptの検査で問題がなくても、記事の内容がよいとは限りません。文字数や見出し構造が正しくても、説明が浅い、根拠が弱い、読者の疑問へ答えていないことがあります。 記事レビューでは、AIによる内容確認とscriptによる形式確認の両方を行ってください。

4. 独自scriptを作る前に、使える既存ツールを探す

目的に合う既存ツールがあるなら、まずそのツールをSKILL.mdから使ってください。使い方が複雑になった部分だけ、独自scriptへまとめてください。

Agent Skills公式のUsing scripts in skillsでは、既存ツールを短いコマンドで利用できる場合、scripts/を作らずSKILL.mdから直接実行する方法が示されています。

公開されているツールを使う例：記事のリンク確認

必要な処理に使える便利なOSSが、すでに公開されている場合があります。 OSSは「Open Source Software（オープンソースソフトウェア）」の略で、プログラムの中身が公開され、定められた利用条件に沿って利用・変更できるソフトウェアです。

たとえば、記事やドキュメントのリンク確認には、OSSのLinkinatorを利用できます。WebサイトやMarkdownに含まれるリンクを調べ、リンク切れの候補を見つけるツールです。

コマンドの書き方が分からない場合は、公式情報の確認からSKILL.mdへの追記までAIへ依頼してください。

記事レビューSkillで、Linkinatorを使ってMarkdown内のリンクを確認したいです。
Linkinatorの公式情報を確認し、使用するバージョンを固定したうえで、
対象の記事ファイルを検査するコマンドをSKILL.mdへ追加してください。
問題のあるリンクは、URLと参照元が分かる形で報告するようにしてください。

AIは、公式情報を確認したうえで、次のようなコマンドをSKILL.mdへ追加できます。

npx linkinator@8.1.0 <記事ファイル> --markdown

コマンドの各部分を覚えるのではなく、実際の記事ファイルで動かし、必要なリンクを検査できるかを確認してください。Linkinatorの機能と現在の使い方は、npmに掲載されているLinkinatorのパッケージページで確認できます。

使っていくと、「社内リンクは検査から外したい」「一部の結果は警告として扱いたい」「結果を記事レビューの報告形式へそろえたい」といった条件が増えることがあります。 AIが毎回長いコマンドを作ったり、結果を同じ形へ直したりしているなら、その部分を独自scriptへまとめるよう依頼してください。

次の処理は、すぐにscript化せず、まずAIにその場で対応させてください。

• 一度しか使わず、繰り返す予定がない処理
• 進め方が固まっておらず、実行のたびに手順が変わる仕事
• AIが標準機能で短く処理でき、失敗や手戻りがほとんどない作業
• 正しい結果と問題のある結果をまだ説明できない仕事

まずSkillを実際の仕事で使ってください。 同じ処理の作り直しや確認漏れが見つかった部分から、既存ツールまたは独自scriptの利用を検討してください。

5. scriptの作成はAIへ依頼し、実際の仕事で試して修正する

scriptを自分で書くより先に、繰り返したい作業、入力するもの、確認条件、欲しい結果をAIへ伝えてください。

記事レビューSkillへ最初のscriptを加える場合は、見出し階層や必須項目の確認など、1つの処理から始めてください。「記事の品質をすべて判定するscript」のように広い範囲を一度に任せず、1つの処理に絞ると、結果が正しいかを確認しながら修正できます。

AIへ依頼する前に、処理内容を言葉で決める

プログラムの書き方ではなく、次の内容を言葉で整理してください。

• 何を入力するか
• 何を確認または処理するか
• 問題がない場合に何を伝えるか
• 問題がある場合に、どの情報を返すか
• どのような例で動作を試すか

記事レビュー用scriptなら、次のように依頼できます。

記事レビューSkillで使う検査scriptを作成してください。

対象：Markdown形式の記事
確認すること：
- タイトルが1つだけある
- H2の次にH4が置かれていない
- frontmatterにtitleとdescriptionがある
- 記事内の画像パスが存在する
- 使いたくない表現の一覧にある文言が使われていない

問題がある場合は、問題の種類、場所、直し方を日本語で表示してください。
対話入力は使わず、記事ファイルを指定して実行できるようにしてください。
正常な記事と、各条件に違反する記事で動作を確認してください。
使い方とSKILL.mdへ追加する実行手順も作成してください。

この依頼なら、AIはコードだけでなく、使い方、確認用の例、SKILL.mdへ入れる指示まで作れます。

AIが作った初版をそのまま完成にしない

AIへscript作成を依頼しても、最初から実務に合うとは限りません。 実際の記事で使い、次の点を確認してください。

• 問題がない記事を、誤って問題ありと判定しないか
• 見つけてほしい問題を見落とさないか
• エラーを見て、直す場所と方法が分かるか
• 何度実行しても同じ確認結果になるか
• 自分の環境で毎回実行できるか

たとえば、コードブロック内の##を見出しとして数えてしまった場合は、「コードブロック内は見出しとして扱わないでください」とAIへ伝え、scriptの修正を依頼してください。画像パスを確認する基準が実際のフォルダ構成と異なる場合も、正しい構成を伝え、scriptの修正を依頼してください。

実際の仕事を1件進め、間違った判定や使いにくい出力を直しながら、最初のscriptを完成させてください。 Skill本体と同じように、scriptも実行後の修正で実務に合う形になります。

6. SKILL.mdには、いつ実行し、問題があれば何をするかを書く

scriptを作成したら、SKILL.mdへ実行する場面、確認する目的、問題が出た後の作業を書いてください。

scriptをscripts/へ置いただけでは、AIが必要な場面で使わない可能性があります。Agent Skills公式のUsing scripts in skillsでは、利用できるscriptと用途をSKILL.mdへ記載し、Skill内の場所が分かる相対パスで実行する方法が示されています。

記事レビューSkillは、次のように構成できます。

article-review/
├─ SKILL.md
├─ scripts/
│  └─ validate_article.py
└─ references/
   └─ review-points.md

フォルダやSKILL.mdの編集もAIへ依頼できます。

作成したvalidate_article.pyを記事レビューSkillへ組み込んでください。
SKILL.mdには、次の流れを追加してください。

1. `references/review-points.md`の観点を使って記事内容をレビューする
2. scriptで形式を検査する
3. 問題があれば記事を修正する
4. scriptを再実行する
5. 内容レビューと形式検査の両方が完了してから結果をまとめる

scriptの場所はSkill内の相対パスで示し、実行方法も記載してください。

SKILL.mdへ追加する内容は、次のように書けます。

## 記事レビューの流れ

1. `references/review-points.md`を読み、記事の内容をレビューしてください。
2. `scripts/validate_article.py`を使って、必須項目、見出し階層、画像パスを検査してください。
3. 問題が見つかった場合は、表示された場所と修正方法を確認し、記事を修正してください。
4. 同じscriptを再実行してください。
5. 問題がなくなった後、内容レビューと形式検査の結果をまとめてください。

SKILL.mdにはscript名だけでなく、「記事内容のレビュー後に使う」「問題があれば記事を直す」「もう一度実行する」「問題がなくなってから完了する」と、前後の作業までつなげて書いてください。

記事レビューでは、次の2つを完了条件にしてください。

• AIによる内容確認：説明不足、読者とのずれ、根拠、重複を確認し、改善案を出す
• scriptによる形式確認：文字数、見出し階層、必須項目、画像パス、リンク、避けたい表現を確認する

形式に問題がなくても、内容に重要な問題が残っていれば修正してください。内容がよくても、画像パスやリンクが壊れていれば公開前に直してください。 両方が終わってからレビューを完了してください。

7. scriptが正しく使えるかは、AIにレビューさせる

ここから扱う確認項目は、scriptの実装を確認するエンジニア向けです。 非エンジニアは技術項目を一つずつ判断せず、scriptとSKILL.mdをAIへ渡し、実行、エラー修正、再実行まで進められるかレビューさせてください。

AIが作成したscriptも、Skillへ入れただけでは実務で安定して使えるとは限りません。 使い方が書かれていない、実行途中で入力を待つ、エラーの場所が分からないといった問題があると、AIは原因の調査からやり直すことになります。

まず、AIへ次のようにレビューを依頼してください。

このscriptとSKILL.mdを、Agent Skillsで繰り返し使えるかレビューしてください。

実際の入力例を使い、次の流れを最後まで試してください。
1. SKILL.mdの指示からscriptを見つける
2. scriptを実行する
3. エラーが出たら、結果を読んで対象を修正する
4. 同じscriptを再実行する
5. 問題がなくなったことを確認する

途中で処理を続けられない箇所、使い方が分からない箇所、
エラーから修正方法を判断できない箇所があれば、scriptとSKILL.mdを修正してください。
修正後、同じ入力例でもう一度試してください。

エンジニアが確認する場合や、AIへ詳しい確認項目を伝える場合は、次の内容を確認してください。

エラーには、AIが修正に使う情報を含める

scriptがエラーとだけ返しても、AIは原因を調べて対応できます。 ただし、対象ファイルや確認条件を調べ直すため、作業が遠回りになります。

記事レビュー用scriptには、次のように問題の場所と直し方を返すよう指定してください。

画像が見つかりません。
記事：article.md
記載されている画像：images/chart-01.png
確認した場所：article.mdと同じフォルダ内のimages
画像を配置するか、記事内のパスを修正してください。

この結果なら、AIは画像を正しい場所へ配置するか、記事内のパスを修正し、同じscriptを再実行できます。

出力が分かりにくい場合は、実際の出力をAIへ渡してください。「問題の場所と直し方まで表示するようにscriptを修正し、同じ入力で再実行してください」と依頼できます。

修正後に同じscriptを再実行できるようにする

検査で問題が見つかったら、AIが記事を直して同じscriptを再実行します。1回目の実行で対象ファイルを意図せず変更したり、不要なファイルを残したりすると、再実行時の結果が変わることがあります。

記事を確認するscriptは、記事そのものを変更せず、問題を報告する役割にすると再実行しやすくなります。 自動修正も行う場合は、検査と修正を分けるか、変更予定を表示してから実行するようAIへscriptの修正を依頼してください。

通常のエラー調査と修正はAIに任せられます。 公開、削除、外部システムの更新など、元に戻しにくい処理をscriptで行う場合だけは、実行対象と変更内容を人が確認する工程を入れてください。

まとめ：同じ処理を繰り返している部分から、AIにscriptを作成してもらう

Agent Skillsのscripts/には、AIに毎回同じ方法で実行させたい処理を入れます。 情報の抽出や形式検査、複数の定型操作はscriptにしやすい一方、記事の意味を読み、問題を考え、改善案を作る作業はAIに任せてください。既存ツールで目的を満たせる場合は、LinkinatorのようなツールをSKILL.mdから使えます。

まずSkillを実務で使い、AIが同じコードを作り直している処理や、確認方法が毎回変わる処理を1つ選んでください。 入力、確認条件、欲しい結果をAIへ伝え、scriptの作成とSKILL.mdへの組み込みを依頼してください。実際の仕事で試し、誤判定や分かりにくい結果があればAIへ修正を依頼してください。

scriptを置くだけで終わらせず、AIが実行し、結果を見て修正し、同じscriptで再検査するところまでSKILL.mdへ入れてください。

Skillを使うと、次にscriptへ移したい処理や、分かりにくいエラーが見つかります。実務のフィードバックからSkill全体を直す方法は、Agent Skillsをどう改善する？実務のフィードバックからSkillを育てる方法で説明しています。

参考資料

• Using scripts in skills（Agent Skills公式）
• Best practices for skill creators（Agent Skills公式）
• Agent Skills Specification（Agent Skills公式）
• Anthropic webapp-testing Skill
• Anthropic docx Skill
• Linkinator