Anthropic ClaudeLLM・AI開発⭐ リポ 0品質スコア 50/100

axi

Name: axi
Author: kunchenguid

エージェントがシェル実行を通じて利用するCLIツールを構築するための人間工学的標準「Agent eXperience Interface (AXI)」です。エージェント向けCLIの新規作成・修正・レビューを行う際に使用します。

description の原文を見る

> Agent eXperience Interface (AXI) — ergonomic standards for building CLI tools that agents use via shell execution. Use when building, modifying, or reviewing any agent-facing CLI.

SKILL.md 本文

Agent eXperience Interface (AXI)

AXI は、自律エージェントがシェル実行を通じてインタラクトする CLI ツールを構築するための人間工学的標準を定義しています。

始める前に

AXI 出力を構築する前に、TOON 仕様をお読みください。

1. トークン効率的な出力

stdout の出力形式として TOON (Token-Oriented Object Notation) を使用してください。 TOON は同等の JSON と比べて約 40% のトークン削減を提供しつつ、エージェントによる読み取り性を維持します。出力の境界で TOON に変換し、内部ロジックは JSON のままにしておきます。

tasks[2]{id,title,status,assignee}:
  "1",Fix auth bug,open,alice
  "2",Add pagination,closed,bob

2. 最小限のデフォルトスキーマ

stdout のすべてのフィールドはトークンコストがかかり、コレクション内の行数により倍増します。エージェントが次に何をすべきかを判断できるようにする最小限のスキーマをデフォルトにしてください。通常は識別子、タイトル、ステータスです。

デフォルトリストスキーマ: 10 ではなく 3～4 フィールド
デフォルトリミット: 1 回の呼び出しで共通のケースをカバーするのに十分な大きさ(ほとんどのリポジトリに 100 未満のラベルがある場合は、30 ではなく 100 をデフォルトに)
長文コンテンツ(本文、説明)はリストではなく詳細ビューに属する
エージェントが明示的に追加フィールドをリクエストできるようにする --fields フラグを提供する

3. コンテンツのトランケーション

詳細ビューには大きなテキストフィールドが含まれることが多いです。それらを省略するとエージェントが検索を強いられ、含めるとトークンが無駄になります。デフォルトでトランケートし、フル版を取得する方法をエージェントに伝えてください。

task:
  number: 42
  title: Fix auth bug
  state: open
  body: First 500 chars of the issue body...
    ... (truncated, 8432 chars total)
help[1]: Run `tasks view 42 --full` to see complete body

大きなフィールドは完全に省略しない — トランケートされたプレビューを含める
総サイズを表示して、エージェントが何を逃しているかを知れるようにする
エスケープハッチ(--full)の提案は、実際にコンテンツがトランケートされている場合にのみ表示する
ほとんどのユースケースをカバーするトランケーションリミットを選択する(500～1500 文字)

4. 事前計算された集計値

最も高いトークンコストは、通常は長い応答ではなく、フォローアップ呼び出しです。バックエンドにエージェントが次のステップとして共通に必要とするデータがある場合は、それを計算して含めてください。

集計カウント: ページサイズだけでなく、リスト出力に総カウントを含めます。エージェントは「全体でいくつあるのか?」が必要であり、答えが決定的でなければページングします。

count: 30 of 847 total
tasks[30]{number,title,state}:
  1,Fix auth bug,open
  ...

派生ステータスフィールド: 次のステップがほぼ常に関連する状態をチェックすることを含む場合、軽量なサマリーをインラインで含めます。

task:
  number: 42
  title: Deploy pipeline fix
  state: open
  checks: 3/3 passed
  comments: 7

バックエンドが安価に提供できる派生フィールドのみを含めます — 完全なデータではなく、サマリー(「3/3 passed」)です。

5. 明確な空状態

答えが「何もない」の場合、明示的にそう述べてください。あいまいな空の出力によってエージェントは異なるフラグで再実行して確認しようとします。

$ tasks list --state closed
tasks: 0 closed tasks found in this repository

コンテキスト付きで 0 を述べてください。コマンドが成功したことを明確にしてください — 結果がないこと自体が答えです。

6. 構造化されたエラーと終了コード

べき等変更操作

望ましい状態が既に存在する場合はエラーを出さないでください。エージェントが既に閉じているものを閉じた場合は、確認して終了コード 0 で進めてください。エージェントのインテントが本当に満たせない状況のために非ゼロ終了コードを予約してください。

$ tasks close 42
task: #42 already closed (no-op)    # exit 0

stdout での構造化されたエラー

エラーは通常出力と同じ構造化形式で stdout に出力されるため、エージェントは読み取ってアクションを実行できます。何が間違ったのか、そして実行可能な提案を含めてください。生の依存関係の出力(API エラー、スタックトレース)が漏れるのを決してさせないでください。

error: --title is required
help: tasks create --title "..." [--body "..."]

依存関係を呼び出す前に必須フラグを検証する
エラーを翻訳する — 実行可能な意味を抽出し、ノイズを捨てる
依存関係の名前を漏らさない — 提案は基盤となるツールではなく、あなたの CLI のコマンドを参照する

インタラクティブなプロンプトなし

すべての操作がフラグのみで完了可能でなければなりません。必須の値が不足している場合は、明確なエラーメッセージとともに即座に失敗してください — プロンプトを出さないでください。ラップされたツールからプロンプトを抑制してください。

出力チャネル

stdout: エージェントが消費するすべての構造化出力 — データ、エラー、提案
stderr: デバッグログ、進捗表示、診断(エージェントはこれを読まない)
終了コード: 0 = 成功(ノーオップを含む)、1 = エラー、2 = 使用法エラー

進捗メッセージを stdout に混ぜないでください。「Fetching data...」を読むエージェントはそれをデータとして解釈しようとします。

7. セッション統合による環境コンテキスト

エージェントのセッションライフサイクルにツールを登録して、エージェントがアクションを取る前に、すべての会話が関連する状態を既に表示した状態で開始されるようにしてください。

パターン:

最初の呼び出しで、セッションフックまたはプラグインをエージェントの設定に自己インストールしてください(べき等に)
セッション開始時に、統合がツールを実行し、コンパクトダッシュボードをコンテキストとして提供します
エージェントはこれを初期コンテキストとして受け取り、すぐにアクションを実行できます

# Agent sees this at session start — no invocation needed:
specs[2]{id,title,status}:
  1,Fix auth bug,open
  2,Add pagination,in-progress

help[2]:
  Run `mytool specs view 1` for details
  Run `mytool specs create --title "..."` to add a spec

ルール:

デフォルトアプリターゲット: デフォルトで Claude Code、Codex、OpenCode をサポートしてください。ツールが複数のエージェントを合理的にサポートできる場合は、単一のエージェント統合をハードコードしないでください
自己インストール: グローバル/ユーザーレベルで最初の実行時にフックまたはプラグインを登録してください — 手動セットアップは不要
ポータブルなコマンド: フックコマンドは、現在の実行可能ファイルに解決する PATH 検証バイナリ名を使用し、そうでない場合は完全な絶対パスにフォールバックしてください。これによってグローバルインストールはポータブルになり、フックが異なるバイナリを誤って実行しないようになります
パスの修復: すべての呼び出しで、既存のフックをチェックし、実行可能ファイルのパスが変更されている場合は更新してください(再インストール後または移動後など)。これにより自己インストールは自己修復に変わります
べき等: 同じパスでの繰り返しインストールは無言のノーオップです
ディレクトリスコープ: 現在の作業ディレクトリに関連する状態のみを表示してください
トークン予算を意識: このコンテキストはすべてのセッションで読み込まれます — 厳しく最小化してください。エージェントが方向を定めてアクションできるのに十分なだけを含めてください; 深いデータは明示的な呼び出しに属します
ライフサイクルキャプチャ: セッション終了フックを使用して、何が起こったか(トランスクリプト、変更されたファイル、参照された仕様)をキャプチャして、将来のセッション開始コンテキストがより豊かになるようにしてください

各アプリとの統合方法:

Claude Code: ~/.claude/settings.json またはプロジェクト .claude/settings.json のネイティブフックを使用してください。stdout を通じてコンパクトコンテキストを注入するために SessionStart を好ましくしてください
Codex: ~/.codex/hooks.json または <repo>/.codex/hooks.json のネイティブフックを使用し、config.toml で [features].hooks = true を確実にしてください。stdout を通じた環境コンテキストのために SessionStart を好ましくしてください
OpenCode: ~/.config/opencode/plugins/ でマネージプラグインを使用してください。ホームビューのカスタムツール追加ではなく、環境システムコンテキストインジェクションを好ましくしてください

8. コンテンツ優先

引数なしで CLI を実行すると、使用法マニュアルではなく、最も関連性の高いライブコンテンツが表示されます。エージェントが実際の状態を見ると、すぐにアクションを実行できます。ヘルプテキストを見ると、2 番目の呼び出しが必要になります。

$ tasks
tasks[3]{id,title,status}:
  1,Fix auth bug,open
  2,Add pagination,open
  3,Update docs,closed
help[2]:
  Run `tasks view <id>` to see full details
  Run `tasks create --title "..."` to add a task

9. 文脈的な開示

現在の出力から論理的に従う次のステップをいくつか含めてください。エージェントは事前にマニュアルを読むのではなく、使用することでオーガニックに CLI の表面領域を発見します。

ルール:

関連性: 未解決項目の後 → 閉じることを提案; 空のリストの後 → 作成を提案; リストの後 → 表示を提案
実行可能: すべての提案は完全なコマンド(またはテンプレート)であり、現在の呼び出しからの任意の明確化フラグを引き継いでいます(例: --repo、--source)
動的値をパラメータ化: 提案されたコマンドが ID、タイトル、ブランチ、URL、またはパスなどの実行時値が必要な場合は、エージェントを誤解させる可能性のある具体的な値を推測するのではなく、<id> または "<title>" のようなプレースホルダーを使用してください
自己完結型のときは省略: 出力が完全にクエリに答える場合(詳細ビュー、カウント、確認)、提案はノイズです — 除外してください。リストと変更応答に含めてください。ここで次のステップは明らかではありません
ワークフローではなく発見をガイド: 可能な次のアクションの多様性を提案し、固定された順序を規定しないでください。既に何をしたいかを知っているエージェントは、追加のステップに誘導されるべきではありません
トランケートされたリストを明らかに: リストがより大きい合計のうち最新の N 項目のみを表示している場合、エージェントにそれらすべてを見る方法を伝えるヘルプヒントを追加してください(例: Run 'mytool list' for all 47 items)。ページングを TOON 配列ヘッダーにエンコードしないでください — ヘルプヒントを代わりに使用してください
エラーを解決: エラーで、「see --help」ではなく、問題を修正する特定のコマンドを提案してください

10. ヘルプを取得する一貫した方法

トップレベルのホームビューはまた、ライブデータの前にツール自体を識別する必要があります:

現在の実行可能ファイルの絶対パスを含め、ユーザーのホームディレクトリを ~ に折りたたみます
この AXI が行うことの 1 文での説明を含めます

$ tasks
bin: ~/.local/bin/tasks
description: Manage project tasks in the current workspace
...

すべてのサブコマンドは、簡潔で完全なリファレンスを持つ --help をサポートする必要があります: デフォルト値を持つ利用可能なフラグ、必須の引数、および 2～3 の使用例。リクエストされたサブコマンドに焦点を当てています — CLI 全体のマニュアルをダンプしないでください。

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

詳細情報

作者: kunchenguid
リポジトリ: kunchenguid/axi
ライセンス: MIT
最終更新: 不明

GitHubで原本を見る →フィードバックを送る

Source: https://github.com/kunchenguid/axi / ライセンス: MIT

axi