uvwt/agentdock

スキルオーサリングガイド

AgentDockのファーストパーティスキルを作成または保守するためのスキルです。スキルの本体はモデルが読み取り可能な説明ドキュメントであり、ツールが実際のチェック、編集、コマンド実行、パッケージ化、インストール、検証を担当します。

ターゲットスキルは以下の2つの部分で構成される必要があります。

可搬性のあるコア契約
+
オプションのホストアダプテーション説明

AgentDock固有のアダプテーション説明を削除しても、スキルのビジネスフロー、パッケージ内参照、環境変数契約、補助スクリプトは完全に利用可能でなければなりません。

使用タイミング

本スキルを使用して以下の処理を行います。

• 新しいファーストパーティスキルの作成
• 既存スキルの変更、リファクタリング、アップグレード
• トリガー説明、本文フロー、参照資料、補助スクリプトの調整
• テスト、サンプル、セキュリティ制約、可搬性チェックの追加
• バージョン更新と、ソース側と現在アクティブなバージョン間の検証

サードパーティスキルの正式なセキュリティレビュー、実際の資格情報の設定、インストール済みバージョンのロールバックには本スキルを使用しないでください。これらは skill-installation に該当します。

コア原則

1. まずモデルがいつこのスキルを選択すべきかを定義し、その後で本文を記述します。
2. スキルはメソッド、境界、ツール選択のみを記述し、統一された実行責任を負いません。
3. スキルのコア契約はホストに依存してはなりません。パッケージ内ファイルは相対パスを使用し、環境は実行ホストから注入されます。
4. シンプルなスキルはまず SKILL.md 1つで構成します。必要な場合にのみ、参照、スクリプト、テストを追加します。
5. 本文、参照、スクリプト、動作を変更した後は、セマンティックバージョンを必ずインクリメントします。
6. 同じ名前で同じバージョンの内容は不変でなければなりません。
7. 環境値、デバイス状態、実行データはスキルパッケージに入れてはいけません。
8. すべての検証は、現在インストールされアクティブなバージョンに対して行う必要があり、ソースディレクトリだけを見てはいけません。
9. ファーストパーティスキルは本スキルの lint を通過しなければならず、パッケージインストールの検証だけでは不十分です。

完全な仕様はパッケージ内 references/skill-package-spec.md を参照してください。

標準フロー

1. 要件とトリガー条件の理解

最初に以下を明確にします。

• ユーザーが実際に解決したい問題
• モデルがどのリクエストでこのスキルを選択すべきか
• どの隣接タスクがこのスキルに属さないか
• どの実際のツールを呼び出す必要があるか
• 補助スクリプト、参照資料、テストが必要かどうか
• ネットワーク、書き込み、削除、資格情報、高リスク動作が含まれるかどうか

「何かの機能のライフサイクル全体を管理する」のような曖昧な説明は避けてください。description はモデルがいつこのスキルを選択すべきかを安定して判断できるようにしなければなりません。

2. 責任範囲の決定

本文には少なくとも以下を記載します。

• 適用シナリオと非適用シナリオ
• 読み取りまたは変更する対象
• デフォルトの読み取り専用動作
• 書き込み操作と破壊的操作の確認ルール
• 失敗時に返すべき証拠

1つのスキルは1つの安定した機能の境界を中心に組織されるべきです。要件が独立した責任をまたがる場合は、複数のスキルに分割する必要があります。

3. ソースディレクトリの作成

一般的なファーストパーティスキルとコミュニティスキルは、デフォルトで独立した agentdock-skills リポジトリに配置されます。

skills/<skill-name>/

AgentDockインストールパッケージにブートストラップされ、ランタイムバージョンに強くバインドされたコアスキルのみがAgentDockメインリポジトリに配置されます。

core-skills/<skill-name>/

必要に応じて構造を選択します。

skills/<skill-name>/
└── SKILL.md

skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
└── tests/

skills/<skill-name>/
├── SKILL.md
├── run.py
└── tests/

形式のために空のディレクトリを作成したり、一般的な統合をAgentDockメインリポジトリに戻したりしないでください。

4. Frontmatterの記述

現在AgentDockが正式に解析する形式：

---
name: example-skill
description: いつ使用し、どのような問題を解決するかを明確に説明
version: 1.0.0
---

要件：

• name は安定した、短い、すべて小文字のハイフン区切り名を使用します。
• description はトリガーシナリオと機能範囲の両方をカバーします。
• version にはセマンティックバージョンを使用します。
• Frontmatterの後には空でないMarkdown本文が必要です。
• 現在のパーサーがサポートしていない環境変数や実行フィールドは追加しません。

5. 可搬性のあるコアの記述

ターゲットスキルの本文とスクリプトは、デフォルトで以下を前提とします。

• 現在の作業ディレクトリはスキルパッケージのルートディレクトリです。
• パッケージ内のリソースには相対パスでアクセスできます。
• 環境変数は現在のプロセス環境から取得されます。
• 実行ホストはツールの選択、ディレクトリの切り替え、環境の注入を担当します。
• AgentDockのインストールディレクトリ、状態ディレクトリ、または専用変数に依存しません。

ルートディレクトリにスクリプトがある場合、汎用的な実行例は以下のように記述します。

printf '%s' '{"skill_action":"status"}' | python3 run.py

以下をコア実行の前提として記述してはいけません。

• ~/.agentdock/skill-store/installed/...
• 固定インストールバージョン番号
• パッケージ内スクリプトやプライベートデータの位置特定のための AGENTDOCK_DIR、AGENTDOCK_HOME、AGENTDOCK_SKILL_DIR
• skill_env、exec_command、skill://
• 固定ユーザー絶対パス
• AgentDockプライベート環境ファイルの能動的な読み取りや source

AgentDockツール呼び出しは、別の「AgentDockアダプテーション/検証」セクションに記載できますが、そのセクションを削除してもスキルは利用可能でなければなりません。

6. 環境変数の宣言

設定が必要な各ターゲットスキルは、本文で明示的に変数を宣言する必要があります。

## 環境変数

| 変数 | タイプ | 必須 | 説明 |
|---|---:|---|
| EXAMPLE_BASE_URL | config | はい | サービスアドレス |
| EXAMPLE_API_KEY | secret | はい | APIキー |

タイプは少なくとも config と secret を区別し、欠落した変数によってどの機能が利用不可になるかを説明します。

ターゲットスキルは変数名と用途のみを宣言し、AgentDockのプライベートな保存パスは宣言せず、実際の値も保存しません。補助スクリプトは現在のプロセス環境からのみ変数を読み取ります。

AgentDockでのローカル検証時、環境値は skill_package env_set/env_unset/env_list によって管理され、exec_command の skill コンテキストによって今回の子プロセスに注入されます。環境はAgentDockのメインプロセスやシステム環境に書き込まれません。

7. 参照資料の記述

references/ に適した内容は以下を含みます。

• 安定したプロトコルの説明
• 長めのチェックリスト
• APIフィールドやエラーコード表
• 毎回完全に読み込む必要のない背景資料

ターゲット SKILL.md はパッケージ内の相対パスを使用します。例：

references/api.md

コア参照契約として skill://<name>/... を記述したり、別のスキルのインストールディレクトリに依存したりしないでください。AgentDockは現在アクティブなパッケージを検証する際に read_file skill://<name>/... でリソースを読み取ることができます。

8. 補助スクリプトの記述

補助スクリプトはオプションのリソースであり、スキル本体ではありません。スクリプトが必要な場合：

• 入力にはstdin JSONオブジェクトを使用します。
• トップレベルのアクションフィールドには一貫して skill_action を使用します。
• 秘密情報は現在のプロセス環境からのみ読み取ります。
• コマンドライン引数で秘密情報を渡さないでください。
• 出力は構造化JSONにします。
• エラーは安定した code と読み取り可能な message を返します。
• 状態チェックは優先的に読み取り専用にします。
• 書き込み操作はユーザー確認ルールに従います。
• ログやエラーに秘密情報を表示しないでください。
• パッケージ内ファイルには相対パスを使用するか、スクリプト自身のディレクトリを基準に位置を特定します。

推奨される入力：

{
  "skill_action": "status"
}

汎用的な実行はスキルパッケージルートディレクトリで行います。

python3 run.py

AgentDockでの検証時は、exec_command の skill: "<skill-name>" を使用して現在アクティブなディレクトリと独立した環境をバインドし、バージョンディレクトリを手動で解決しません。

9. 可搬性lintの実行

本スキルの run.py は以下を提供します。

• status：lintのバージョンとルール数を報告します。
• lint：ターゲットスキルの可搬性コアとホストバインディングの問題をチェックします。

入力例：

{
  "skill_action": "lint",
  "source": "/path/to/agentdock-skills/skills/example-skill"
}

結果には以下が含まれます。

• portable
• error_count
• warning_count
• 各issueの code、severity、ファイル、行番号、説明、修正提案

ハードコードされたインストール済みバージョンディレクトリ、AgentDock専用ディレクトリ変数への依存、AgentDock環境ファイルの能動的な読み取り、固定ユーザー絶対パスは error です。AgentDock専用ツールやURIがターゲット SKILL.md に出現する場合は warning であり、それらがオプションのアダプテーション説明にのみ存在することを確認する必要があります。

インストール済みディレクトリに対してlintを実行する場合、パッケージルートディレクトリにあるAgentDockインストーラが生成した .agentdock-install.json は無視されます。このファイルはホストインストールのレシートであり、スキルパッケージの内容ではありません。同じ名前のファイルがパッケージ内の他のディレクトリにあれば、通常通りスキャンされます。

AgentDockで新しいバージョンの skill-authoring をインストールした後、以下のように実行できます。

exec_command
  skill: skill-authoring
  cmd: python3 run.py
  stdin: {"skill_action":"lint","source":"/path/to/source"}

ファーストパーティスキルを作成または変更する場合、portable は true でなければなりません。warningは1つずつ修正するか、オプションのホストアダプテーションに属する理由を説明する必要があります。

10. テストの記述

テストは実際のリスクをカバーし、少なくとも以下を考慮します。

• Frontmatterと本文が解析可能であること。
• 入力がJSONオブジェクトでない場合に明確に失敗すること。
• 未知の skill_action に対して明確に失敗すること。
• 環境変数が欠落している場合、変数名のみを報告し、値を漏らさないこと。
• 読み取り専用の状態チェックが書き込みを生成しないこと。
• 破壊的アクションに確認がない場合に拒否すること。
• ログやエラーに秘密情報が含まれないこと。
• プラットフォームや依存関係が欠落している場合に診断可能な情報を返すこと。
• パッケージがルートディレクトリから相対コマンドで実行されること。
• スクリプトがAgentDockのプライベートディレクトリに依存しないこと。

11. セキュリティと品質チェック

提出前に以下をチェックします。

• パッケージ内に実際のパスワード、トークン、Cookie、認証キャッシュ、セッションファイルがないこと。
• .env、キャッシュ、データベース、スクリーンショット、ダウンロードファイル、実行結果がないこと。
• __pycache__、*.pyc、node_modules、コンパイル成果物がないこと。
• 固定ユーザー絶対パス、シンボリックリンク、パスエスケープがないこと。
• 旧式の統一実行プロトコル、旧式の環境ツール例、旧リストがないこと。
• ネットワークターゲット、ファイル書き込み、削除、アップロード、権限変更が明確に説明されていること。
• 依存関係のインストールが隠れて実行されないこと。

以下の生成または復元は明確に禁止されています。

• agentdock.yaml
• skill_run
• skill_env_manage
• AGENTDOCK_OPERATION
• PLUGIN_* 旧プロトコル
• 旧式の operation または entrypoint リスト
• 統一スキル実行基盤または旧スキルランタイム

デバイスのプライベート状態やAgentDockの環境値はホストにのみ属し、パッケージに入れてはいけません。

12. バージョンインクリメント

• 単に本文の誤字を修正し、動作判断に影響を与えない場合は、パッチバージョンをインクリメントできます。
• 互換性のある能力、変数、アクション、参照を追加する場合は、マイナーバージョンをインクリメントします。
• 責任範囲を変更したり、既存の能力を削除したり、互換性のないフローを導入する場合は、メジャーバージョンをインクリメントします。

インストール前に、現在インストールされているバージョンと新しいソースを比較してください。同じバージョンで異なる内容を上書きしてはいけません。

13. 検証とローカルインストール

少なくとも以下を完了します。

1. ディレクトリとFrontmatterのチェック
2. バージョンが正しくインクリメントされているかのチェック
3. 禁止ファイル、シンボリックリンク、実際の秘密情報のチェック
4. 補助スクリプトの構文チェックと組み込みテストの実行
5. skill-authoring lint の実行、portable=true の確認、warningのレビュー
6. skill_package validate によるパッケージレベルの正当性チェック
7. skill_package install によるインストールとアクティベーション
8. agentdock_context による名前と説明が軽量インデックスに含まれていることの確認
9. read_file skill://<name>/SKILL.md による現在アクティブな本文の確認
10. 参照がある場合、少なくとも1つの参照を読み取り
11. 補助スクリプトがある場合、exec_command skill=<name> を使用して現在アクティブなバージョンに対して読み取り専用の status を実行
12. 代表的な低リスクアクションを1つ実行し、実行できない場合は実際の理由を記録

skill_package validate はパッケージが合法的にインストール可能かどうかを担当します。本スキルの lint はファーストパーティの作成品質と可搬性を担当し、両者は互いに代替できません。

環境変数

本スキル自体には環境変数は必要ありません。作成対象のターゲットスキルがビジネス変数を宣言し、実行ホストがそれを現在の子プロセスに注入することを要求します。

完了基準

以下のすべての条件を同時に満たした場合にのみ完了とみなします。

• 説明が安定してトリガー可能で、範囲が明確であること。
• 可搬性コアがAgentDockのプライベートディレクトリやツールパラメータに依存しないこと。
• パッケージ内スクリプトがスキルルートディレクトリから相対パスで実行可能であること。
• skill-authoring lint が portable=true を返し、warningが1つずつ処理されていること。
• セキュリティチェック、テスト、skill_package validate が通過していること。
• 新しいバージョンがインストールされ、アクティブ化されていること。
• agentdock_context と skill:// の読み取りが新しいバージョンを参照していること。
• 現在アクティブなバージョンの実際の読み取り専用検証が通過していること。
• 秘密情報、デバイスのプライベート状態、旧式アーキテクチャの逆流がないこと。