agent-skill-stack

エージェントスキルスタックを構築する

ユーザーが実際に達成したいことに合わせて、役に立つ最小限のスタックを構築します。異なる依頼に対して、特定の分野の例や固定のライフサイクルを決して押しつけないでください。

1. ユーザー向けの説明レベルを選ぶ

デフォルトでは平易な言葉で説明するモードを使います。ユーザーがパス、リビジョン、ハッシュ、マニフェスト、静的解析、実行時の詳細を知る必要はないものとします。

平易な言葉で説明するモードでは、次の内容を示します。

• ユーザーが達成しようとしていること
• 日常的な言葉で説明した手順
• すでに利用できる機能
• 推奨、任意、重複、または不適切なスキル
• 各候補がどの程度広く使われているか
• インストール時の安全性チェックと安全な試行に合格したかどうか
• 必要となる可能性があるアカウントアクセスや外部への操作

ソースパス、リビジョン、ファイルのフィンガープリント、生のスコア、監査証拠、依存関係の詳細は内部記録に保持します。ユーザーが技術的な詳細を求めた場合、または十分な情報に基づく同意に特定の技術的事実が必要な場合に限り、それらを提示します。

2. ワークフローを動的に導き出す

references/workflow-model.mdを読みます。依頼に含まれる分野の言葉ではなく、ユーザーが求める最終的な結果から始めます。

結果、アクセス範囲、コスト、スタックに実質的な影響を与える質問だけをします。成功から逆算してワークフローを導き出し、利用可能な開始点から順方向に検証します。

以前の番号付きフローを再利用しないでください。すべての依頼に調査、コンテンツ作成、公開、分析、保存、自動化が必要だと決めつけないでください。ユーザーの目的に必要な場合に限り、ステップを追加します。

各ステップの操作が1つで、主な結果が1つ、アクセス境界が1つ、観測可能な成功条件が1つになるまで分解します。技術的な機能カードは内部にとどめ、ユーザーには短く平易なフローを示します。

3. まずローカルインデックスを検索する

references/local-index-and-profiles.mdを読みます。

最新のローカルスキルインデックスがある場合は、ファイルシステムやインターネットを調べる前にそれを検索します。インデックスがない、または古い場合は、関連するスキルのルートから再構築します。

python3 scripts/skill_index.py build \
  --root ~/.codex/skills \
  --root ~/.codex/plugins/cache \
  --root .codex/skills \
  --root ~/.agents/skills \
  --root ~/.hermes/skills \
  --output ~/.codex/skill-index.json

インデックスには、名前、概要、別名、対象範囲、機能に関する用語、更新時刻、内部ファイルのフィンガープリントが保存されます。スキルを実行することはなく、使用履歴も保存しません。

現在のプロジェクトに.codex/skill-stack.jsonがある場合は、そこに記載された有効なスキルとルーティング規則を第一候補のスタックとして扱います。対象範囲に含まれない機能がある場合、またはユーザーが代替案を求めた場合に限り、プロファイルの外を検索します。異なるローカルルートに同じ名前の項目がある場合は、審査対象として扱い、暗黙に統合しないでください。

4. 間接的な補助機能も含めて機能を対応付ける

必要な各ステップについて、次の内容を内部に記録します。

• 必要な入力、操作、出力
• 制約、頻度、規模
• ローカル／外部読み取り／外部書き込みの境界
• アカウント、権限、承認の要件
• 成功条件と代替手段
• 前後のステップ

次に、関連する場合に限り、品質／スタイル、正確性、コンプライアンス、プライバシー、ローカライズ、データ品質、オーケストレーション、可観測性といった横断的なニーズを検討します。

タイトルの類似性ではなく、入力 -> 操作 -> 出力に基づいてスキルを対応付けます。これにより、ユーザーの分野が名前に含まれていなくても、自然な文章を書くという要件にHumanizerを対応させられます。

各ステップにスキルを1つずつ無理に割り当てないでください。1つのスキルが複数のステップをカバーすることもあれば、あるステップで別のスキルではなく、ツール、MCP、コネクター、または汎用エージェント機能が必要になることもあります。

5. 4 つの視点から検索する

references/discovery-ranking.md を読んでください。未対応の各機能について、次の観点から検索します。

1. 直接的なニーズ：ユーザーの分野とアクション。
2. 基盤となる操作：実際の変換処理またはデータタスク。
3. 支援する成果：品質、安全性、スタイル、コンプライアンス、評価、モニタリング。
4. 接続方法：CLI、MCP、API、コネクター、ブラウザー自動化、ストレージ、引き継ぎ。

中国語と英語の別名、動詞、名詞、出力、関連用語を展開して検索してください。可能な場合は、タイトル、説明、見出し、SKILL.md の全内容を検索します。

完全なレジストリはないため、複数の情報源を利用してください。

• ローカルの Skill インデックスとインストール済みインベントリ。
• GitHub コネクター、または GitHub のファイル／リポジトリ検索。
• npx skills find <query> と skills.sh。
• 利用可能な場合は、agentskill.sh または別のレジストリ。
• 幅広いウェブ検索とプラットフォーム固有の調査には OpenCLI。

ブラウザーを利用する OpenCLI 検索は順番に実行してください。ユーザーの承認なしにログインしたり、認証情報を追加したり、コネクターを有効にしたりしないでください。

6. 候補を検証して順位付けする

検索結果はすべて候補として扱い、推奨とは見なさないでください。正規のリポジトリと正確な Skill パスを特定します。Skill 全体と、インストールによってアクセス可能になるすべての実行可能ファイルを読みます。

次の場合は、候補を却下するか、隔離してください。

• ソースまたは主張されている機能を検証できない。
• その構造ではインストールできない。
• 必須の依存関係に互換性がない、または利用できない。
• 重要な認証情報へのアクセス、データのアップロード、プロンプトインジェクション、破壊的な操作、難読化について説明がないままである。
• 公開、送信、購入、削除、または実アカウントの変更を伴うテストしか実施できない。
• ライセンスまたはプラットフォームの利用規約により、意図した使用に重大な不確実性がある。

これらの条件を通過した候補を、references/discovery-ranking.md の評価基準で順位付けします。実世界での採用状況とコミュニティの根拠は、スコアの 25% を占めます。不明な値は不明のままにしてください。

必要なすべての成功条件を満たす、最小限のスタックを優先してください。候補は次のように分類します。

• 必須：成果を達成するために必要です。
• 有用：品質、安全性、または効率を高めます。
• 代替：相互に置き換え可能な候補です。
• 非推奨：ブロックされている、重複している、互換性がない、または不確実性が高すぎる候補です。

7. 競合と適用範囲を分析する

references/security-installation.md を読んでください。ID、アクティベーション、指示、リソース、依存関係、データ形式、権限、コンプライアンスに関する競合を確認します。

重複がある場合は、プライマリ Skill を 1 つ選ぶ、ヘルパーへの引き継ぎ範囲を限定する、代替候補を相互排他的に保つ、または重複する候補をインストールしないことで解決します。

タスク固有の機能には、プロジェクトローカルの Skill とプロジェクトの Skill Stack Profile を優先してください。広く利用可能にする必要がある機能に限り、グローバルインストールを使用します。

8. 推奨事項をわかりやすい言葉で提示する

デフォルトの出力：

1. 達成したいこと：簡潔に言い換えます。
2. 作業の進め方：このリクエストに合わせて、短い番号付きの手順を示します。
3. すでにあるもの：既存の役立つスキルと、見つかった不足点を示します。
4. 推奨する組み合わせ：必須、役立つもの、代替案、非推奨を示します。
5. 選定理由：適合性、導入状況、安全性の確認、安全な試行、競合について、日常的な言葉で説明します。
6. 判断が必要なこと：アカウントへのアクセス、有料サービス、外部への公開、インストールするものの選択を示します。

已具备、推荐、可选、不建议、安全检查通过、安全试跑通过、最近确认可用などのラベルを使用します。デフォルトの応答ではハッシュやローカルパスを表示しないでください。

必要に応じて查看技术详情を提示します。技術的な表示には、正規のソース、リビジョン、ファイルフィンガープリント、正確なインストール先、生の証拠、依存関係、権限、ロールバックの詳細を含めることができます。

ユーザーが再利用可能な成果物を求めている場合は、構造化JSONから共有可能な推奨カードを作成します：

python3 scripts/render_stack_card.py \
  --input /path/to/stack-card.json \
  --output /path/to/stack-card.svg

カードは技術的なパスや生のハッシュがなくても理解できるようにします。目標、選択したスキル、それぞれの役割とステータス、安全上の境界、確認日を含めます。

9. 同意を得てからインストールする

推奨しただけでは、インストールの許可を得たことにはなりません。ユーザーが選択した後、references/security-installation.mdに従います。

デフォルトでは段階的なインストールを行います。選択したすべてのスキルが必須ゲートを通過し、正確に固定された識別情報を持ち、未解決の競合がなく、既存のインストール先を上書きせず、ユーザーが一括実行を明示的に承認した場合に限り、ワンクリックでの一括インストールを許可します。

すでにダウンロードして確認済みのスキルディレクトリでは、まずプレビューします：

python3 scripts/stage_install.py \
  --source /path/to/skill-a \
  --dest ~/.codex/skills \
  --manifest ./skill-stack-lock.json

承認を得た後にのみ、--applyを付けて再実行します。認証情報を黙って追加したり、新しい権限を受け入れたり、インストール済みのスキルを上書きしたり、外部データを公開・送信・削除したりしてはいけません。

ユーザーがスタックを選んだ後、ドライランモードでプロジェクトプロファイルを作成することを提案します：

python3 scripts/project_profile.py \
  --project /path/to/project \
  --name project-stack \
  --skill skill-a \
  --skill skill-b

ユーザーがプロファイルを確認した後にのみ、--applyを使用します。

10. 想起チェックを実行する

インストール後またはプロファイルの変更後に、パフォーマンスベンチマークではなく想起チェックを実行します：

1. タスク名を明示した直接的なリクエスト。
2. 異なる言葉を使った自然な言い換え。
3. 文章の品質確認、ファクトチェック、コンプライアンスなどの補助スキルが呼び出されるべき補助的なリクエスト。

適切なメインスキルと補助スキルが選択され、無関係なスキルが選択されないことを確認します。3/3 種類の表現をすべて正しく認識のような簡潔な結果を報告し、生のプロンプトやルーティングの詳細は技術的な表示に含めます。

ユーザーのプロンプト履歴、ヒット／ミスのログ、ルーティングに関するフィードバックを収集または保存してはいけません。