Agent Skillsでソフトウェア開発工程をWorkflow化

2026年8月12日更新：今週はPromptを3件だけ棚卸しする

Agent Skillsの公開仕様では、SkillはSKILL.mdを中心に、スクリプト、参照資料、テンプレートなどをまとめたフォルダーとして定義されています。必要なときに本文や関連ファイルを読み込む段階的な方式も採用されています。詳細はAgent Skillsの公開仕様で確認できます。

結論は明確です。Agent Skillsはモデルを再訓練して、チームの開発手法を永久に覚えさせる機能ではありません。SOP、ツール操作、確認条件、参照資料を必要な場面で注入し、繰り返し使える手順に変える仕組みです。今週は同じ内容を何度も書いているPromptを棚卸しし、工程を標準化してからSkill化してください。

このページを読むべき人

AIによる開発手順を統一したい研究開発責任者
チームのPromptとプロジェクト規則を管理するプラットフォームエンジニア
AIをテスト、レビュー、リリース工程へ組み込みたいAIエンジニア

最初から巨大なAI Agent Workflowを作る必要はありません。まずは、手順が安定している小さな作業を1つ選びます。

まず、Promptがチーム資産にならない理由を切り分ける

チャットに貼るPromptは、個人の会話履歴に埋もれます。誰が、どの版を使ったか分からず、更新理由も追跡しにくい構造です。プロジェクト固有の規則、テストコマンド、レビュー基準が別々の場所にあると、AIが古い手順を参照する危険もあります。

方式	保管場所	再利用性	検証しやすさ	向いている用途
単発Prompt	チャット、個人メモ	低い	低い	調査、試作
Agent Skill	リポジトリ内の`SKILL.md`と関連資料	高い	中程度	定型作業、レビュー
AI Agent Workflow	Workflow定義、状態、実行履歴	高い	高い	テスト、承認、リリース

Agent Skillsの仕様では、SKILL.mdにnameとdescriptionを置き、必要に応じてscripts、references、assetsを追加できます。説明欄の上限は1024文字で、Skill名にも形式上の制約があります。こうした構造があるため、会話文ではなくコードレビューの対象にできます。(仕様の該当箇所)

Agent SkillsはAIにチーム開発を学習させるのですか。

いいえ。ここでいう「学習」は、モデルのパラメーターを更新する意味ではありません。タスクに合うSkillを検出し、SKILL.mdや関連ファイルをコンテキストへ読み込み、手順として再利用する意味です。モデル微調整はモデル自体の振る舞いを変える手段ですが、Skillは外部の手順と資料を管理する手段です。

次に、工程知識を1つの参照経路へ集約する

Skillの本文にすべてを書き込むと、すぐに長文化します。公開仕様では、本文は500行未満、5000トークン未満を推奨し、詳細な情報は参照ファイルへ分ける設計が示されています。必要な資料だけを後から読み込むためです。

実務では、次のように分けます。

code-review/
├── SKILL.md
├── scripts/
│   └── run-checks.sh
├── references/
│   ├── review-policy.md
│   └── security-rules.md
└── assets/
    └── review-template.md

SKILL.mdには、作業の開始条件、実行順、利用するコマンド、失敗時の処理、完了条件を書きます。組織の規約や長い設計資料はreferences/へ置き、担当者と更新日を明記してください。

Skill説明の最適化ガイドでは、どのタスクでSkillを使うかを説明欄に具体的に書く方法が示されています。対象タスク、入力条件、対象ファイルを明記し、「開発を支援するSkill」のような広すぎる表現は避けてください。

注意：Skillの説明が曖昧だと、必要な場面で起動されません。個人PC固有のパスや、担当者しか分からない略語も残さないでください。別の実行環境で再現できるかを、登録前に確認します。

第1段階：SOPをSKILL.mdへ変換する

Promptをそのまま貼り付けるのではなく、作業を機械的に分解します。次の5項目を順番に埋めると、ソフトウェア工程向けのSkillになります。

開始条件
どの種類のIssue、Pull Request、ブランチで起動するかを決めます。
入力と参照先
対象ファイル、設計書、設定ファイル、テストデータを指定します。最新情報の取得先も固定します。
実行手順
調査、編集、フォーマット、静的解析、テストの順序を記述します。スクリプトを使う場合は、入力と終了コードを明確にします。
停止条件
テスト失敗、依存関係の不一致、機密情報の検出、仕様不足など、作業を止める条件を列挙します。
成果物と報告形式
変更ファイル、テスト結果、未解決事項、手動確認が必要な箇所を決めた形式で出力させます。

Skillでスクリプトを利用する方法でも、Skillフォルダーからの相対パスでスクリプトを呼び出す構成が説明されています。「テストを実行してください」だけで終わらせず、実行コマンドと失敗時の報告形式まで固定するのがポイントです。

ソフトウェア開発SOPは、どのようにAgent Skillへ書きますか。

「目的」だけでなく、「順番」と「合格条件」まで書きます。例えばコードレビューなら、差分確認、関連テスト、セキュリティ確認、変更概要、未確認項目の報告を1つの手順にします。リリース承認や本番データ変更まで含む場合は、Skillだけで完結させず、後述するWorkflowへ移します。

第2段階：実行できることと、実行してはいけないことを分ける

Agentはコマンドを実行できますが、実行能力と安全な権限設計は別問題です。読み取り専用の調査、ローカルで戻せる変更、外部システムへの書き込みを同じ権限で許可すると、誤操作の影響範囲が広がります。

操作レベル	例	推奨設定	人工確認
読み取り	`git diff`、ログ確認、静的解析	自動許可を検討	原則不要
可逆変更	テストブランチの編集、整形、生成ファイル更新	隔離環境で許可	差分確認
高リスク書き込み	本番デプロイ、外部チケット更新、秘密情報変更	明示許可と承認	必須

クライアント側で許可するツールを限定できる場合でも、危険な権限を一括で解除してはいけません。公式CLI資料には、許可するツールの指定方法と、権限確認をスキップする危険なオプションが掲載されています。後者は隔離環境以外では使わない方が安全です。(Claude Code CLIの公式資料)

環境変数、APIキー、SSH鍵をSkill内に直接保存しないでください。開発用、検証用、本番用で認証情報を分け、実行環境側で注入します。必要であれば、VPSSparkの利用環境相談で、権限を分けた遠隔開発環境の構成を確認できます。

第3段階：Agentの作業をテストと門番につなぐ

Agentが「完了しました」と報告しても、成果物が正しいとは限りません。Skillには、実行操作だけでなく、テスト、停止条件、エラー報告、人工承認を組み込む必要があります。

最低限、次を記録します。

変更前後の差分
実行したコマンドと終了結果
単体テスト、結合テスト、静的解析の結果
失敗した場合のログ保存先
人が確認する項目
次の工程へ進めない条件

GitHub Actionsの公式仕様では、ジョブ間の依存関係をneedsで指定できます。前段のテストが失敗した場合、後続ジョブを止める構成にできます。生成物やテストログはWorkflowのアーティファクトとして後続ジョブへ渡せます。(Workflow構文の公式資料)

AI Agentが開発工程を守ったか、どう検証しますか。

会話の印象ではなく、ログと成果物で検証します。「テスト実行済み」という文章だけを合格条件にせず、指定コマンドの終了結果、テストレポート、差分、承認記録がそろっていることを判定条件にします。開発担当、テスト担当、プラットフォーム担当で、手順が実行可能かを確認すると、Skillの記述ミスも見つけやすくなります。

第4段階：SkillとWorkflowの担当範囲を分ける

Skillは、作業方法を教える部品です。一方、Workflowは、状態、分岐、再試行、スケジュール、通知、承認を管理する実行基盤です。複雑な処理を1つの長いSKILL.mdへ詰め込むと、どこで失敗したか分かりにくくなります。

チームの状態	選ぶ構成	実装範囲	次へ進む条件
初期	単一Skill	コードレビュー、テスト実行	手順が安定する
中期	Skillの組み合わせ	調査、実装、検証を分割	失敗箇所を自動判定できる
成熟	完全なWorkflow	状態管理、再試行、承認、通知	実行履歴と責任分界が必要になる

Workflow定義はリポジトリで管理し、ジョブを分けて実行履歴を残します。公式資料でも、Workflowは複数のジョブで構成され、イベント、手動実行、スケジュールを起点に動かせる仕組みとして説明されています。

本番反映を含む場合は、環境ごとの承認と秘密情報を分離します。デプロイ環境には承認ルール、ブランチ制限、環境別の秘密情報を設定できます。(デプロイ環境の公式資料)

第5段階：PromptからWorkflowへ移行する実行順

移行は、次の順番なら戻りやすくなります。

繰り返し作業を棚卸しする
コードレビュー、テスト修正、依存関係更新など、同じPromptを使う作業を抽出します。
SOPを人間向けに確定する
先に人間が実行できる手順へ整理します。曖昧な規約を先にSkill化すると、曖昧さも自動化されます。
単一Skillを作る
SKILL.mdに開始条件、手順、停止条件、成果物を記述します。詳細資料はreferences/へ分離します。
代表ケースで検証する
成功例だけでなく、テスト失敗、仕様不足、権限不足、対象外ファイルを含むケースを用意します。
権限と実行環境を分離する
読み取り、可逆変更、高リスク書き込みを分け、開発用の隔離環境で動かします。
Workflowへ接続する
テスト、レビュー、承認、通知、再試行が必要になった段階で、SkillをWorkflowの部品として組み込みます。
保守責任者を置く
開発ツールや規約が変わったら、SkillとWorkflowを再検証します。標準やクライアントの能力が変化した時点で、移行手順も見直してください。

2026年8月12日時点で、公開仕様と公式資料から確認できるのは、Skillの形式、段階的な読み込み、関連ファイル、ツール権限、Workflowのジョブ依存関係と承認機能です。Skillがモデルのパラメーターを更新する機能だとする根拠はありません。(Agent Skillsの仕様)

現在の開発環境だけで進める方法は、初期費用を抑えられる一方、個人PC依存、権限の混在、実行ログの不足、長時間タスクの中断が起きやすい点が弱点です。チームで同じAI Agent Workflowを動かすなら、環境を毎回手作業で作る方式より、隔離された遠隔開発環境へ寄せた方が管理しやすくなります。短期の検証や一時的な開発環境が必要なら、日本向けのVPSSpark利用環境を候補に入れてください。長期の固定負荷や物理デバイス接続が必要な場合は、自社環境の方が適しています。

SOPを整理した後で、Agent Workflowの実行環境、権限分離、長時間タスクの運用まで進めるなら、まずはVPSSparkのサービス概要で利用条件を確認してください。重要なのはSkillを増やすことではなく、検証できる工程だけを段階的に自動化することです。