スキルの作成
既存のオーナーを再利用する
パッケージを作成する前に、既存のスキルカタログを調査してください。リポジトリ作業の場合、ターゲットカタログと、許可されたワークスペース内の関連するすべてのソースカタログを検索します。許可されたライブラリ作業の場合、Rundeskのカタログとスキルリストを使用します。タスクのアクセス境界を回避するためにライブライブラリを開かないでください。可能性のある一致の説明を読み、その本文と関連する参照を確認してから決定してください。
要求された機能が、ユーザーの意図、ワークフロー、および権限を共有している場合は、既存のオーナーを拡張してください。新しいルーティングサーフェスを作成する代わりに、サポートスクリプト、参照、またはテストをそこに追加します。機能に個別のルーティング、判断、権限、または証明が必要な場合にのみ、新しいスキルを作成します。その区別を記録し、似た名前だけが正当化の理由として扱われないようにします。
成果物を選択する
- スキルは指示の境界です：いつ行動するか、どの判断を適用するか、どの手順に従うか、そして結果をどのように証明するか。
- ワークフロースクリプトは、反復的なローカル変換、検証、またはオーケストレーションのための決定論的メカニズムです。
- 統合は外部サービス境界を追加します：認証情報、アカウント、ネットワーク障害、権限、またはリモート効果。
単発の自動化はそのプロジェクトに、あるエージェントのプライベートな反復コマンドはそのエージェントのスクリプトエリアに保持してください。将来のターンでそれを使用するためにルーティングや判断が必要になる場合にのみ、スクリプトをスキルにパッケージ化します。エージェントが再解釈しなければならない散文で決定論的コードを置き換えないでください。
再利用可能なワークフロースクリプトをリリースする前に、再利用可能なワークフロースクリプトをお読みください。また、認証情報、プロファイル、OAuth、ネットワーク、またはリモート効果を使用する場合は、外部サービス統合もお読みください。
安全に配置する
ライブでの作成またはインストールが許可されている場合にのみ、localにプライベートスキルを作成してください。ドラフト、レビュー、リポジトリ変更、または隔離されたテストの場合は、名前付きワークスペースまたは一時ディレクトリに留まり、結果が後でどこに行くかを発見するためにライブラリを検査または変更しないでください。
許可されたプライベートスキルの場合は、RUNDESK_HOMEから派生させたり、絶対パスを埋め込んだりせずに、Rundeskにライブラリを問い合わせてください。サンプル名を置き換えます：
skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"
<library>/local/<name>/SKILL.md を作成し、名前付きエージェントに付与します：
"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes
付与は、現在のターンではなく、エージェントの次のターンで検出可能になります。他のインストール用にスキルを作成する前に、スキルカタログの公開をお読みください。公開されたスキルはカタログリポジトリに属し、localには属しません。
必要な形状のみを使用する
<name>/
├── SKILL.md 必須: ルーティングとコア手順
├── rundesk.json オプション: 必要な環境値
├── scripts/ オプション: 再利用可能なコマンド
├── tests/ オプション: カタログのテストエリアが所有していない場合のスクリプト契約
├── references/ オプション: 条件付きで読み込まれる詳細
└── assets/ オプション: コピーまたは出力されるマテリアル
オプションパスはコンテンツがある場合のみ作成してください。README、チェンジログ、インストールガイド、作成履歴は省略してください。
ルーティングを最初に書く
フロントマターにはnameとdescriptionのみがあります。
nameをディレクトリに一致させます。最大64文字の小文字、数字、および単一のハイフンを使用します。- ユーザーの意図によってルーティングします。スキルに名前を付けていない間接的なリクエストも含みます。「Use when」、「Apply when」、または同等の適用可能性を示す表現で始めます。プロンプトフレーズはトリガーではありません。
- 2つの短い文を目指します：適用可能性、次に提供される専門ワークフローまたは知識です。近いミスの可能性がある場合にのみ「Do not use」を追加します。ボディが読み込まれる前にルーティングに必要な概念のみを含めます。ステップ、テスト、利点の主張、実装の詳細は省略します。ファイルタイプ、ツール、またはフォーマットは、スキルをトリガーすべきかどうかを決定する場合にのみ名前を付けます。
- 正しくルーティングできる最短の説明を使用します。1,024文字は目標ではなく上限です。すべてのトリガーをそこに配置します。なぜなら、各保持者はすべてのターンでそのコストを支払い、ルーティングが成功するまでボディは利用できないからです。
# 悪い例: ルーティングに役立たない実装と検証が埋め込まれている。
description: リリースノートを作成する際に使用します。Git履歴を読み、Markdownを書き、コミットをグループ化し、リンクをチェックし、検証を実行し、正確なフォーマットで簡潔な内部バージョンと公開バージョンを生成します。
# 良い例: 意図、提供される判断、および最も近い境界のみを述べている。
description: リリースされたリポジトリ変更からリリースノートを作成する際に使用します。検証済みの履歴に基づいた、オーディエンスに焦点を当てたワークフローを提供します。未リリースの計画には使用しないでください。
行動ガイダンスのみを保持する
実行順序に従って命令形のステップを使用します。読者が推論、編集、および通常のツールを使用できることを前提とします。実行を変更したり、可能性の高い失敗を防いだり、必要な詳細をルーティングしたりする場合にのみ、文を保持します。
- コア手順、1つの強力なデフォルト、および明白でない落とし穴を
SKILL.mdに保持します。 - 脆弱な操作には正確なコマンドを使用します。複数のアプローチが機能する場合は簡潔な判断を使用します。
- 制約が防ぐ失敗を説明し、説明できない強調を追加しないでいます。
- 各参照を、いつ読むべきかの説明とともに紹介します。単一の情報源を維持し、言い換える代わりにリンクします。
- 背景、プロセス履歴、日付の主張、および他の場所ですでに読み込まれているルールを削除します。
- 観察された契約と推奨されるデフォルトを区別します。技術的な制約をソースし、実際のトラップを症状、原因、置き換え、および観察可能な証明として教えます。
SKILL.mdを500行未満に保ちます。条件付きの詳細は、リンクされた参照に1レベル移動します。
コンテキスト予算を管理する
| パート | トークンコスト | そこに保持するもの |
|---|---|---|
description | すべてのターン | 最短の完全なトリガー |
SKILL.md | ルーティング後 | コア手順、デフォルト、落とし穴 |
references/ | 読み込まれたとき | 条件付きの詳細と大規模な例 |
scripts/ | 出力がコンテキストに入る | 出力が制限された決定論的な作業 |
tests/ | 検証のみ | 実行可能な契約とエッジケース |
assets/ | 使用時 | テンプレートと出力マテリアル |
短い例を優先します。スクリプトの出力を、次の決定に必要なものに制限します。
スキル全体を検証する
-
ディレクトリ名、フロントマターの名前、説明の構文、および制限を検証します。
-
付与が必要な場合は、それを適用し、次のターンで確認します：
"$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT" "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT" -
各スクリプトの参照が所有するエッジマトリックスと直接実行可能エントリポイントを実行します。
-
異なる新しいターンで、直接リクエスト、間接リクエスト、および近いミスを試します。作業前にボディと必要な参照が読み込まれることを確認します。コピーされたプロンプトフレーズではなく、カテゴリ別にルーティングを修正します。
-
重要なスキルの場合は、スキルなしの新しいベースラインと同じタスクを比較します。次に、別のテストエージェントに、期待される実装なしでそれを使用させます。成果物とコマンドを直接レビューします。エージェントの要約は証明になりません。実質的な改善をもたらさないガイダンスを削除します。
-
生成された文章を実行可能な正確性とは別にレビューします：ルーティングの精度、実行順序、有用な判断、簡潔さ、重複、および参照の規律。スクリプトテストがグリーンでも文章の品質を証明しません。事実に基づく約束をソースまたは観察し、実行可能な主張をテストし、部分的な真実を狭めます。便利な集計を保持しながら実際の関係や結果を変更する敵対的な反例で意味論的な主張に挑戦します — ミューテーションチェックは間違ったテストオラクルを修復できません。空の成功、重複する証拠、およびデータ依存の出力セクションを含む、インターフェース全体をレビューします。