GitHub AgentOps 実践ガイド

第4章：Skills 設計

この章で扱うこと

  • 反復タスクを「入力/出力/手順/チェック/失敗時対応」として資産化する
  • Skills を運用資産として継続更新するための設計

Skills の位置付け

Skills は、エージェントに対する 反復タスクの実行手順（Runbook） です。 プロンプトの都度チューニングではなく、「入力が揃えば同じ品質で実行できる」状態を目指します。

典型例は次の通りです。

  • 依存更新（理由・影響・検証・ロールバックが揃った実行仕様）
  • テスト追加（受入基準→テスト観点→粒度選定→実装→安定化）
  • ドキュメント整備（参照更新、リンク検証、表記の統一）
  • リファクタ（振る舞い不変、差分最小、分割、検証）

設計原則（失敗しにくい Skill）

  • 入力が具体：対象範囲、制約、受入基準、検証手順が明記されている
  • 出力が具体：PR 形式、生成物、証跡（テスト結果、ログ）が揃う
  • 手順が最短：余計な探索を減らし、変更差分を最小化する
  • 品質ゲートが内蔵：実行コマンドと期待結果が書かれている
  • 失敗時の分岐：典型的な失敗パターンと切り分け方がある

Skill のテンプレ（推奨）

Skill は Markdown で次の章立てにすると、レビューと再利用が容易です。

  • 目的
  • 入力（必須）
  • 出力（成果物）
  • 手順
  • チェック（品質ゲート）
  • 失敗時の対応

ポイントは、Skill 自体が「実行仕様」になっていることです。 入力が不足している場合は、エージェントが勝手に補完せず「不足」を返せるようにします。

ミニ例：SKILL.md 断片（ドキュメント整備）

形式は一例です。実運用では、対象リポジトリの品質ゲート（npm test 等）と整合させてください。

# docs-update

## 目的
- 誤字/表記ゆれ/参照不整合を修正し、読者の迷いを減らす

## 入力（必須）
- 対象ページ/章（パス）
- 制約（最小差分、slug/アンカー互換性維持、生成物は編集しない等）
- 検証コマンド（例: `npm test`）

## 出力（成果物）
- 修正済み Markdown ファイル
- PR 本文に記載する主要改善点と検証結果

## 手順
1. 対象章を精読し、誤字/表記ゆれ/参照不整合/未完成マーカーを洗い出す
2. 修正し、章内/章間参照（リンク/用語）を確認する
3. 検証を実行し、結果を PR 本文に記載する

## チェック（品質ゲート）
- `npm test`

## 失敗時の対応
- lint/link-check のエラー箇所を切り分け、最小修正で再実行する

運用（更新・棚卸し）

Skills は一度作って終わりではなく、運用で磨きます。

  • 変更理由（なぜ変えたか）を残す
  • 破壊的変更は避け、必要なら新 Skill として追加し段階移行する
  • 四半期棚卸しで、コマンド/依存/リンクの陳腐化を点検する

Companion 資産（参照先）

Companion repo: itdojp/GitHub-AgentOps-companion

  • skills/dependency-update/SKILL.md
  • skills/add-tests/SKILL.md
  • skills/docs-update/SKILL.md
  • skills/refactor-safe/SKILL.md

章末チェックリスト（ドラフト）

  • Skill が入力/出力/手順/チェック/失敗時対応を持つ
  • Skill の適用条件（前提）と非スコープが明確
Edit this page on GitHub