skill-doctor

Name: skill-doctor
Author: nyldn

github.com/nyldnエージェントワークフロー4.3k60 回インストール1 日前に更新

リポジトリ

skill-doctor について

Claude Octopus環境を15カテゴリで診断するCodex CLI向けスキルです。プロバイダー、認証、フック、状態、スケジューラーなどを確認し、環境のトラブルシューティングや重要なワークフロー前の点検に使えます。

主な機能

0115カテゴリの診断を実行
02カテゴリ別およびライブのプロバイダーチェック
03詳細レポートとJSONレポート
04ソフトウェア依存関係の個別確認
05確認を得て修復可能な問題に対処

活用シーン

01動作しないインストール環境の調査
02更新後の設定確認
03デモ前のプロバイダー認証確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/nyldn/claude-octopus --skill skill-doctor

インストール後、Claude Code で/skill-doctorを入力して読み込まれたか確認します。

同梱ファイルagents/openai.yaml

詳細

ホスト：Codex CLI — このスキルはClaude Code向けに設計され、Codex向けに調整されています。相互参照コマンドでは、/octo:*スラッシュコマンドではなく、Codexにインストール済みのスキル名を使用します。アクティブなCodexシェルとサブエージェントツールを使用してください。現在のセッションで利用できることが確認できるまでは、プロバイダー、モデル、またはホストのサブエージェントが使用可能だと断言しないでください。ホストツールに相当するものについては、skills/blocks/codex-host-adapter.mdを参照してください。

環境診断

概要

15のチェックカテゴリにわたって環境診断を実行します。Doctor 2.0は、設定ミスのあるプロバイダー、読み込み済みまたはキャッシュされたプラグインの古いバージョン、無効なプラグインの組み立て、書き込み不可の状態、終了していない実行記録、孤立プロセスの痕跡、壊れたフックなど、Claude Octopusが正しく動作する妨げとなる問題を特定します。

基本原則： ワークフローで問題が表面化する前に検出します。

使用するタイミング

次の場合にこのスキルを使用します：

何かが動作しないものの、原因がわからないとき
プラグインのインストールまたは更新後
デモや重要なワークフローの実行前
プロバイダーが適切に認証されているか確認するとき
スケジューラー、フック、スキルが正しく設定されているか検証するとき

次の場合は使用しないでください：

初回セットアップ（設定を案内する/octo:setupを使用してください）
プロジェクトのワークフロー状態の確認（/octo:statusを使用してください）
アプリケーションコードのデバッグ（/octo:debugを使用してください）

手順

ステップ1：プラグインのルートを解決して完全な診断を実行する

Octopusのスクリプトを実行する前に、このリゾルバーを使用します。まずアクティブなホストのルートを優先し、次に安定ルート、最後にインストール済みCLIを使用してください。診断の実行中に、安定リンクを作成または置き換えないでください。これを単一のBash呼び出しとして実行します。

OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-}}"
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then
  OCTO_BIN="$(command -v octopus)"
  OCTO_LINK_HOPS=0
  while [[ -L "$OCTO_BIN" ]]; do
    OCTO_LINK_HOPS=$((OCTO_LINK_HOPS + 1))
    if [[ "$OCTO_LINK_HOPS" -le 40 ]]; then
      OCTO_BIN_DIR="$(cd -P "$(dirname "$OCTO_BIN")" 2>/dev/null && pwd -P)" || { OCTO_BIN=""; break; }
      OCTO_LINK_TARGET="$(readlink "$OCTO_BIN")" || { OCTO_BIN=""; break; }
      case "$OCTO_LINK_TARGET" in
        /*) OCTO_BIN="$OCTO_LINK_TARGET" ;;
        *) OCTO_BIN="$OCTO_BIN_DIR/$OCTO_LINK_TARGET" ;;
      esac
    else
      OCTO_BIN=""
      break
    fi
  done
  if [[ -n "$OCTO_BIN" ]]; then
    OCTO_BIN_DIR="$(cd -P "$(dirname "$OCTO_BIN")" 2>/dev/null && pwd -P)" || OCTO_BIN_DIR=""
    [[ -z "$OCTO_BIN_DIR" ]] || OCTO_PLUGIN_ROOT="$(cd "$OCTO_BIN_DIR/.." 2>/dev/null && pwd -P)"
  fi
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="$(
    find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \
      | sed 's#/scripts/orchestrate.sh$##' \
      | { grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' || true; } \
      | sort \
      | tail -1
  )"
fi
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry doctor diagnostics."
  exit 1
fi
export OCTO_PLUGIN_ROOT
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

これにより、15のチェックカテゴリすべてが実行され、整形されたレポートが表示されます。インストールカテゴリは、安定ルートが存在しない、または一致しない場合に報告しますが、修復は行いません。

ステップ2：カテゴリで絞り込む（任意）

ユーザーから特定の領域について質問された場合は、ステップ1のリゾルバーを再利用し、最後のdoctor --verboseの呼び出しを次のいずれかの行に置き換えます。これらは置き換え用の行であり、単独で実行するシェル呼び出しではありません。OCTO_PLUGIN_ROOTは同じBash呼び出し内で解決する必要があります。

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers --live
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor companions
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor config
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor updates
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor state
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor smoke
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor hooks
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor scheduler
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor skills
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor conflicts
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor agents
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor recurrence
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor cache
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor installation

ステップ3：依存関係を確認してインストールする

ステップ1のリゾルバーを再利用し、最後の呼び出しを依存関係チェッカーに置き換えて、不足しているCLI、ステータスラインの設定、推奨プラグインを確認します。

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" check

チェックで不足している依存関係が報告された場合は、インストールを提案します。

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" install

これにより、Codex CLI、jq、ステータスラインリゾルバーが自動インストールされます。Antigravity CLI（agy）のセットアップ状況は検出され、インストール方法とともに報告されます。プラグイン（claude-mem、document-skills）については、ユーザーが手動で実行する必要がある/plugin installコマンドが表示されます。

ステップ4：詳細出力またはJSON出力

上記と同様に、これらをステップ1のリゾルバー呼び出しの最後の行として実行します。

# Detailed output for troubleshooting
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json

# Combine: specific category + verbose
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose

Doctor 2.0のJSONでは、常に次の外側の形式が使用されます。

{
  "schema_version": "10.0",
  "summary": {"passed": 0, "warnings": 0, "failures": 0, "exit_code": 0},
  "results": []
}

ステータスがfailのチェックがある場合、summary.exit_codeとプロセスの終了コードはいずれも1になりますが、標準出力には引き続き有効なJSONが出力されます。警告は構造化された形式で出力されますが、コマンドは失敗しません。不明なフラグ、不明なカテゴリ、カテゴリ引数の複数指定は終了コード2の使用方法エラーです。全項目のスキャンとして再試行しないでください。

providers --liveは、対象を限定した明示的なAGY機能チェックです。実際の小規模なリクエストを1回使用して、CLIのバージョン、ライブモデルカタログ、キーリング認証、設定済みモデル、印刷モードのディスパッチを検証します。起動フックや定期的な事前チェックから実行しないでください。カタログまたは認証の段階で失敗した場合は、通常のagyを起動してブラウザーでサインインを完了するようユーザーに伝えてください。AGYには個別のログイン用シェルサブコマンドはありません。macOSでキーリングエラーが発生した場合は、「キーチェーンアクセス」でAntigravity CLIの項目を開き、「アクセス制御」の設定を確認するよう案内してください。

ステップ 5：対話型の修復（修復可能な問題がある場合は必須）

診断の実行後、修復可能な問題が 1 つでも見つかった場合は、必ず AskUserQuestion を使って修復を提案してください。手順を表示するだけではいけません。修復を実行するかどうかを尋ねてください。

安定ルートの修復には制限があり、明示的な許可が必要です。まず、次の方法で変更案を提示してください。

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" repair --dry-run

ユーザーがその修復を明示的に許可した場合に限り、次を実行できます。

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" repair --apply

リゾルバー内や doctor の自動フォローアップとして、安定リンクを再作成しないでください。キャッシュのクリーンアップ、古い PID のクリーンアップ、ログインフロー、パッケージのインストール、プラグインの更新にも明示的な確認が必要です。

承認された修復を実行する前に、その対象と操作を正確に再提示してください。設定の修復には、検証済みの同階層の一時ファイルとアトミックな名前変更を使用してください。いずれかの手順が失敗した場合は、元のファイルを維持し、失敗を報告してください。キャッシュのクリーンアップ、古い PID のクリーンアップ、ログインフロー、パッケージのインストール、プラグインの更新には、常に明示的な確認が必要です。修復後は、まず影響を受けたカテゴリのみを再実行し、その後、全項目のスキャンを提案してください。

RTK がインストールされていない場合：

AskUserQuestion({
  questions: [{
    question: "RTK saves 60-90% on bash output tokens. Install it now?",
    header: "Install RTK",
    multiSelect: false,
    options: [
      {label: "Install via brew (Recommended)", description: "brew install rtk — fast, macOS"},
      {label: "Install via cargo", description: "cargo install rtk-token-killer"},
      {label: "Skip", description: "Continue without RTK"}
    ]
  }]
})

ユーザーがインストールを選択した場合は、インストールを実行し、その後フックのセットアップを提案してください。

RTK はインストール済みだが、macOS/Linux でフックが設定されていない場合：

Windows Git Bash では、rtk init -g を提案しないでください。RTK はそこで CLAUDE.md の挿入モードを使用するため、フックのチェックはスキップされたと報告してください。

AskUserQuestion({
  questions: [{
    question: "RTK is installed but the Claude Code hook isn't active. Configure it?",
    header: "RTK Hook",
    multiSelect: false,
    options: [
      {label: "Run rtk init -g (Recommended)", description: "Auto-installs Claude Code bash hook on macOS/Linux"},
      {label: "Skip", description: "I'll configure it later"}
    ]
  }]
})

任意のプロバイダーが見つからない場合：

AskUserQuestion({
  questions: [{
    question: "Some providers are missing. Install them?",
    header: "Providers",
    multiSelect: true,
    options: [
      {label: "Codex CLI", description: "npm install -g @openai/codex"},
      {label: "Antigravity CLI", description: "Install agy, then verify with agy --version && agy models"},
      {label: "Skip all", description: "Continue with available providers"}
    ]
  }]
})

認証の有効期限が切れている場合： 有効期限が切れたプロバイダーのログインコマンドを実行するか、ユーザーに確認してください。

修復可能な問題が複数ある場合： 1 つずつ質問するのではなく、適切な場合は multiSelect を使い、単一の AskUserQuestion にまとめてください。

チェックカテゴリ

カテゴリ	チェック内容
`providers`	Claude Code のバージョン、Codex CLI のインストール状況、Antigravity CLI のインストール状況、Perplexity API キー、Ollama のローカル LLM（サーバーとモデル）、サーキットブレーカーの状態、プロバイダーのフォールバック履歴
`companions`	任意のコンパニオンツールと連携機能
`auth`	各プロバイダーの認証状態
`config`	プラグインのバージョン、インストール範囲、機能フラグ、厳密な `claude plugin validate` の結果
`updates`	読み込み済み、インストール済み、カタログ、キャッシュの各バージョン、Claude マーケットプレイスの自動更新、再読み込みの必要性
`state`	プロジェクトの state.json、ワークスペースとプローブキャッシュの書き込み可能性、古い結果、終了していない実行、孤立 PID と古い PID の証拠
`smoke`	スモークテストのキャッシュ、モデル設定
`hooks`	hooks.json の有効性、フックスクリプト
`scheduler`	スケジューラーデーモン、ジョブ、予算ゲート、キルスイッチ
`skills`	スキルファイルの読み込み状況と有効性
`conflicts`	競合するプラグインの検出
`agents`	エージェント定義、ワークツリーの分離、CLI の登録、バージョン互換性
`recurrence`	失敗パターンの検出 — 繰り返される品質ゲートの失敗、ソースのホットスポット、48 時間の傾向にフラグを立てます
`cache`	キャッシュのサイズ、新しさ、衛生状態
`installation`	読み込み済みプラグインのルート、安定ルート、ホストスコープのインストールメタデータ、コンテキストプロファイル

ソフトウェア依存関係のインストール状況は、ステップ 3 の scripts/install-deps.sh check で個別に確認します。Node.js、jq、プロバイダー CLI、 RTK によるトークン圧縮、ステータスラインリゾルバー、推奨プラグインが対象です。

結果の解釈

正常な出力

すべてのチェックに合格しており、対応は不要です。

よくある問題と修正方法

問題	修正方法
Codex CLI が見つからない	`npm install -g @openai/codex` を実行するか、`codex login` でインストールします
Antigravity CLI が見つからない	`agy` をインストールし、`agy --version` と `agy models` で確認します
Perplexity が設定されていない	`export PERPLEXITY_API_KEY="pplx-..."` を実行します（任意）
認証の有効期限が切れている	`codex login` を再実行します。AGY の場合は、通常の `agy` を起動し、ブラウザーでサインインを完了します
サーキットブレーカーが OPEN	プロバイダーで一時的な障害が 3 回以上連続して発生しています。クールダウンを待つか、プロバイダーのステータスを確認します
状態が古い	`.octo/state.json` を削除して再初期化します
hooks.json が無効	`hooks.json` の構文を確認します。有効な JSON である必要があります
RTK がインストールされていない	インストールを提案します：`brew install rtk && rtk init -g`（トークンを 60〜90% 節約できます）。brew と cargo install のどちらを使うか、AskUserQuestion で提案します
RTK はインストール済みだが、フックが設定されていない	macOS/Linux では `rtk init -g` を提案します。Windows Git Bash では、RTK が CLAUDE.md のインジェクションモードを使用するため、スキップされたことを報告します
RTK の節約量統計を利用できない	まず bash コマンドをいくつか実行し、その後 `rtk gain` を確認してトークンの節約量を確認します
プラグインが競合している	競合するプラグインをアンインストールするか、スコープを調整します

他のスキルとの連携

シナリオ	対応方法
Doctor がプロバイダーの不足を検出した	設定するために `/octo:setup` を提案します
Doctor がプロジェクトの古い状態を検出した	確認するために `/octo:status` を提案します
Doctor がフックのエラーを検出した	hooks.json の修正方法を案内します
すべてのチェックに合格しても、ユーザーに問題が残っている	詳細に調査するために `/octo:debug` を提案します

コンテキストと強度のプロファイル

インストールレポートには、任意のコンテキスト設定が 2 つ表示されます。

OCTOPUS_CONTEXT_PROFILE は、コンテキストの動作として core、orchestration、full のいずれかを選択します。 octopus profile コマンドでこの設定を読み書きします。
OCTOPUS_HOOK_PROFILE は、任意のコンテキストフックプロファイルを core、orchestration、full で上書きできます。

これらの設定が制御するのは、任意のコンテキスト関連の処理のみです。安全性フックやライフサイクルフックが無効になることはありません。フックプロファイルレジストリが存在しないか無効な場合は、フェイルクローズします。

OCTO_PROFILE は、budget、balanced、quality の値を取る別個の従来型の強度設定です。どちらのコンテキスト設定の別名でもなく、安全性フックが無効になると主張するために使用してはなりません。

従来型の強度プロファイル

一部の古いワークフローパスでは、モデルの選択、フェーズのスキップ、コンテキストの詳細度を制御する強度設定として OCTO_PROFILE を使用します。この設定は、上記の任意のコンテキストフックプロファイルとは別個のものです。

Doctor が確認する項目

コンテキストプロファイル：OCTOPUS_CONTEXT_PROFILE の値。デフォルトは core
任意のフックプロファイル：設定されている場合は OCTOPUS_HOOK_PROFILE、それ以外の場合はコンテキストプロファイル
従来型の強度：従来型のワークフローで読み取られる場合の OCTO_PROFILE
フックの適用範囲：任意のコンテキストフックのみ。安全性フックとライフサイクルフックは引き続き有効です
モデルのヒント：各フェーズで推奨されるモデル（sonnet/opus）
コンテキストの詳細度：圧縮／標準／完全

従来型の強度の概要

項目	budget	balanced	quality
モデル	すべて Sonnet	合成に Sonnet + Opus	ほとんどのフェーズで Opus
フェーズ	コンテキストが指定されている場合、discover をスキップ	再発見をスキップ	すべてのフェーズを実行
コンテキスト	圧縮	標準	完全にインライン化

任意のコンテキストプロファイルの概要

項目	core	orchestration	full
任意のコンテキストフック	オフ	ワークフローコンテキストのみ	プロファイル管理対象のすべてのコンテキストフック
安全性フックとライフサイクルフック	有効	有効	有効

プロジェクトのティアに関するヒント

OCTO_TIER が設定されている場合は、その値も報告します。これは推奨のヒントであり、厳格なポリシーではありません。

ティア	Doctor の指針
`prototype`	高速なチェックを優先し、プロバイダーへの高コストな一斉リクエストの前に警告します
`mvp`	バランスの取れたデフォルト設定を使用し、リスクの高い変更にはコンセンサスを求めます
`production`	完全な検証、セキュリティレビュー、より厳格なリリースゲートを推奨します

未設定の場合は OCTO_TIER=unset と表示し、プロジェクトのリスクプロファイルが安定している場合にのみ設定するよう提案します。

リモートセッションのチェック

CLAUDE_CODE_REMOTE=true または OCTOPUS_REMOTE_SESSION=true の場合は、次の内容を報告します。

リモートセッションが検出されたこと
明示的な自律性の設定がない場合、自律モードがデフォルトで有効になること
時間とクォータを節約するため、プロバイダーのプローブをスキップすること
OCTOPUS_REMOTE_STATUSLINE=full の場合を除き、完全な HUD が無効になること
クラウドのセットアップスクリプトでプロバイダーの CLI のインストールが必要になる場合があること

設定に関する案内に限り /octo:setup を提案してください。リモートセッション内でプロバイダーに対する対話型ログインを推奨しないでください。

ランタイムコンテキスト

doctor は、オーケストレーションプロンプトにプロジェクト固有のコンテキスト（API エンドポイント、環境変数、テストコマンド、ビルド手順）を提供する、プロジェクトレベルの RUNTIME.md をチェックします。

Doctor のチェック項目

プロジェクトのルートに RUNTIME.md が存在するか（.octopus/RUNTIME.md と .claude-octopus/RUNTIME.md もチェックします）
存在しない場合は、次のテンプレートから作成するよう提案します：cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.md
存在する場合は、少なくとも1つのセクションに内容が記入されていることを確認します（テンプレートのデフォルト値だけではないこと）

重要な理由

RUNTIME.md がないと、オーケストレーションプロンプトにプロジェクト固有の詳細が含まれず、テストコマンド、環境変数、ビルド手順について一般的なアドバイスしかできません。内容が記入された RUNTIME.md があれば、すべてのワークフローの精度が向上します。

クイックリファレンス

Claude Code のネイティブな /doctor コマンドを維持するため、/octo:doctor は v9.41.0 で削除されました。この手動スキルを明示的に呼び出すか、CLI を直接実行してください。

指示する内容／実行するコマンド	アクション
`/octo:skill-doctor`	Claude Code 内で15カテゴリすべてを実行します
`octopus doctor providers`	プロバイダーのインストール状態のみをチェックします
`octopus doctor auth --verbose`	認証状態の詳細を表示します
`octopus doctor --json`	機械可読形式で出力します
`bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose`	CLI が利用できない場合に認証状態の詳細を表示します
`bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json`	CLI が利用できない場合に機械可読形式で出力します

octopus CLI が PATH にない場合は、Step 1 のリゾルバーで OCTO_PLUGIN_ROOT を解決してエクスポートし、同等の scripts/orchestrate.sh コマンドを直接実行してください。

Markdown 対応

ログインしてコメント

基本情報

作者: nyldn
リポジトリ: nyldn/claude-octopus
カテゴリ: エージェントワークフロー
インストール数: 60
GitHub スター: 4,337

問題を報告