開発者向け Claude Skills と SKILL.md：VS Code、JetBrains、Cursor

ほとんどのチームは、Claude Skillsの使い方を2つのいずれかの誤った方法で運用しています。SKILL.mdを単なるゴミ箱のように使っているか、巨大なプロンプトの切り貼りから抜け出せずにいるかのどちらかです。

どちらのアプローチも雑です。Skillsを実際の開発ワークフローで機能させたいなら、それらをプロンプトの詩ではなく、コードや運用ロジックとして扱う必要があります。

Claude Skillsは SKILL.md を中心とするディレクトリで、オプションのスクリプト、参照ファイル、アセットから構成されます。これらは段階的開示（progressive disclosure）によって機能します。エージェントはまず、スキル名や説明のようなコンパクトなメタデータのみを読み込み、タスクが一致した場合にのみ完全な指示を読み取ります。これにより、エージェントはセッションの開始から膨大になることなく、多くのスキルを有効な状態に保つことができます。

もし Hermes Agent も運用している場合、同じディスク上の構造は、Hermesが文書化している agentskills スタイルの仕様と整合しています。条件付きアクティベーション、ハブのスキャン、シークレットと設定の区別は、Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices に詳細が記載されています。

Anthropic自身のガイダンスは、意図された役割分担をかなり明確に示しています。CLAUDE.md は、永続的で常にオンになるプロジェクトコンテキスト用です。Skillsは、オンデマンドで読み込まれるべき再利用可能な知識、プレイブック、呼び出し可能なワークフロー用です。これにより、Skillsは、vibe codingよりも構造化されたいが、完全な Spec Kit スキャフォールドほどの儀式は必要ない場合、仕様駆動開発ループ（仕様定義、計画、実装、検証）をエンコードするための自然な場所となります。Claude Codeのスキルが、ポータブルな代替案やIDE統合された代替案と比較してどうなるかは、GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows を参照してください。自分で作成するのではなく、そのループを事前に構築・強制される形でインストールしたい場合は、Superpowers が、ブレインストーミング、計画、サブエージェントレビュー、TDDといったまさにこの種のスキルスタックを、インストール可能なプラグインとしてパッケージ化しています。

Claude Codeは、従来のカスタムコマンドを同じメカニズムに統合したため、レガシーの .claude/commands/*.md ファイルは引き続き機能しますが、Skillsの方が長期的にはより良い形態です – そして、AI駆動開発ワークフロー における最も再利用可能なビルディングブロックです。

Claude Skillsの使用場面：CLAUDE.md vs Skills vs Hooks

同じチェックリスト、同じデプロイプレイブック、同じコードレビュー基準、または同じ内部APIの落とし穴をチャットに貼り付け続ける場合、Claude Skillを作成する価値があります。Anthropicは、同じ手順を繰り返し再利用する場合、または CLAUDE.md のあるセクションが事実ではなくプロセスに成長した場合に、スキルを作成することを明示的に推奨しています。これは、FAQの質問「Claude Skillとは何か、いつ使うべきか」に対する実用的な答えです。一般的な好みや広範なリポジトリルールではなく、再現可能な手順のためにSkillを使用してください。

本当の利点は、コンテキストコストと挙動に対するコントロールです。良いSkillは関連がある場合にのみ読み込まれますが、肥大化した CLAUDE.md はすべてのセッションで読み込まれます。Anthropicは、オンデマンドの読み込みがエージェントを現在のタスクに集中させるため、CLAUDE.md を短く保ち、ドメイン知識や手順をSkillsに移すことを推奨しています。

私の意見のあるルールはシンプルです。指示がすべてのセッションに適用されるべきであれば、CLAUDE.md に属します。指示が再利用可能な方法、チェックリスト、またはワークフローであり、時々のみ重要であれば、Skillに属します。アクションがすべての一致するイベントで自動的に発生しなければならなければ、おそらくそれはSkillではなく、フックに属します。Anthropicの機能概要は、これらのツールをほぼ正確にその階層モデルで位置づけています。

各レイヤーの実用的な臭い（smell）：同じ指示をすべてのチャットに貼り付けている場合、それはSkillです。CLAUDE.md のセクションが段階的なプロセスに成長した場合、それをSkillに抽出してください。ファイルが保存されるたびに静かに発火させたいものは、フックを書いてください。知っておくべき第4のレイヤーもあります：タスクがメインセッションを邪魔したくないノイジーな中間出力（コードベースの探索、大規模なテスト実行など）を生成する場合、それは サブエージェント の仕事であり、Skillではありません。

Claude SkillsのIDEサポート：VS Code、JetBrains、Cursor、Codex

Claude Code は、CLI、デスクトップ、VS Code、JetBrains、Web、およびモバイル関連のリモートコントロールフローで動作します。Anthropicは、CLIを最も完全なローカルサーフェスとして説明しており、IDE統合は、CLI固有の機能の一部を犠牲にして、エディターネイティブなレビュー、ファイルコンテキスト、より緊密なワークフローのエクソノミクス（操作性）を優先します。設定、プロジェクトメモリ、MCPサーバーはローカルサーフェス間で共有されるため、.claude の設定は特定のエディターに閉じ込められることなく、あなたについてこられます。

VS Codeについて、Anthropicは拡張機能がエディター内で推奨されるインターフェースであると述べています。これは、計画のレビュー、インライン差分、ファイル言及サポート、CLIへの統合アクセスを提供します。同じインストールフローは、Cursorへの直接パスも公開しています。JetBrainsについては、現在サポートされているリストには IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLandが含まれ、差分表示、選択の共有、ファイル参照ショートカット、診断の共有がプラグインに組み込まれています。

JetBrainsのサポートは、多くの開発者が思っているよりも良いです。IDEの統合ターミナルから claude を実行する場合、統合機能が自動的に有効になります。外部ターミナルから開始する場合、Anthropicは /ide コマンドを文書化しており、Claude CodeをJetBrainsセッションに再接続します。また、ClaudeがIDEが見るのと同じファイルを見るように、同じプロジェクトルートから起動することを明示的に推奨しています。JetBrainsで自動編集モードを使用する場合、AnthropicはIDEの設定ファイルが編集可能なサーフェスの一部になる可能性があるため、その環境では手動承認の方が安全なデフォルトであると警告しています。

ここで、より大きなポイントです。Claude Skillsは、Claude Codeだけのものではありません。Agent Skillsはオープンスタンダードです。公式のAgent Skillsクイックスタートは、同じスキルがVS Code（GitHub Copilot）、Claude Code、OpenAI Codexで動作すると述べており、OpenAI自身のCodexドキュメントは、SkillsがCodex CLI、IDE拡張機能、アプリで利用可能であると述べています。Agent Skills実装ガイドは、重要なポータビリティの詳細を追加しています：.agents/skills がクライアント横断の慣習として台頭しており、一部のクライアントは実用的な互換性のために .claude/skills もスキャンします。

したがって、私が推奨する実用的な互換性ルールは次の通りです。Claude Codeのみを最初に構築する場合、.claude/skills で作成してください。真にクライアント横断のポータビリティを望む場合、オープンなAgent Skillsの形状をターゲットにし、.agents/skills を正規パスとして使用してください。これら2つの目標が同一であるかのように装わないでください。それらは関連していますが、同一ではありません。

簡単な互換性リファレンス：

SKILL.mdファイルの構造、フォルダレイアウト、保存場所

適切なSkillは、リポジトリのルートに置かれたランダムなMarkdownファイルではなく、フォルダです。コア仕様は、SKILL.md ファイルを含むディレクトリを必要とし、オプションの scripts/、references/、assets/ ディレクトリを許可します。SKILL.md は、YAML frontmatterに続き、Markdownによる指示を含む必要があります。仕様では、name と description が必須であり、name は小文字、数字、ハイフンを使用する64文字以内に制限され、compatibility は実際の環境要件のみに使用し、allowed-tools は実装間で明示的に実験的であるとされています。

Claude Codeは、名前のディレクトリから名前を導出でき、description が欠落している場合は最初の段落にフォールバックできるため、ポータブルな仕様よりも少し緩やかです。ポータビリティや予測可能性を気にするなら、それに頼るべきではありません。Claude.aiはディレクトリ名が name フィールドと一致することを要求し、より広い仕様ははるかに多くの文字を許可しているにもかかわらず、カスタムスキルアップロードパスでは説明を200文字に制限しています。ポータブルな選択肢は、明示的な name を設定し、ディレクトリを同一に保ち、厳しい制限内に収まる正確な説明を書くことです。これで、FAQトピック「SKILL.mdファイルには何を含めるべきか」を曖昧にせず、答えられます。

この退屈な構造から始めましょう：

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Skills互換クライアント間のポータビリティがClaude Codeの利便性よりも重要である場合、同じ内部形状を保持し、.claude/skills/ を .agents/skills/ に置き換えます。フォルダ構造は、どちらの場合も同じアイデアです。

Claude Codeの場合、保存場所は明確です。プロジェクトスキルは .claude/skills/<skill-name>/SKILL.md に、個人スキルは ~/.claude/skills/<skill-name>/SKILL.md に、プラグイン配布スキルは <plugin>/skills/<skill-name>/SKILL.md 以下に配置されます。Anthropicは、組み込みスコープ間の優先順位を、エンタープライズ > 個人 > プロジェクトとして文書化しており、プラグインスキルは plugin-name:skill-name のような名前空間化された形式を使用して衝突を避けます。Windowsでは、~/.claude は %USERPROFILE%\.claude に解決され、CLAUDE_CONFIG_DIR を使用してベースディレクトリ全体を再配置できます。

プロジェクトスコープと個人スコープの選択は明確です。Skillがそのコードベースと強く結合されている場合（例えば、特定のクラスタ名を知るデプロイプレイブックや、チームの規約に調整されたレビュー基準など）、リポジトリ内の .claude/skills/ を使用してください。プロジェクト間であなたと一緒に移動するSkills（個人のチェックリスト、一般的な変更履歴ジェネレーター、好まれるデバッグワークフローなど）には ~/.claude/skills/ を使用してください。dotfilesリポジトリに置くようなものは、個人スコープに属します。

いくつかの鋭い端（sharp edges）を覚える価値があります。SKILL.md は、その大文字小文字を正確に命名する必要があります。AnthropicのPDFガイドは、kebab-caseのフォルダ名を推奨し、スキルフォルダ内に README.md を配置しないことを明示的に述べています。なぜなら、運用ドキュメントは SKILL.md または references/ にあるべきだからです。同じガイドは、SKILL.md の命名が大文字小文字を区別することを強調しています。これらは退屈な制約ですが、退屈な制約こそがツールを信頼できるものにします。

Claude Codeは、モノレポのために正しいことをします。サブディレクトリ内で作業している場合、ネストされた .claude/skills/ ディレクトリを自動的に検出するため、パッケージレベルやサービスレベルのスキルに理想的です。また、現在のセッション中、既存のスキルディレクトリのライブ変更を監視します。唯一の再起動トラップは、セッション開始時に存在しなかったトップレベルのスキルディレクトリを作成することです。Anthropicは、新しいディレクトリを監視できるように再起動が必要な場合としてこれを文書化しています。

Claude Skillsベストプラクティス：説明、スクリプト、スコープ

無用のSkillを作成する最速の方法は、LLMに一般的なトレーニング知識から1つ発明させることです。Anthropicのベストプラクティスガイドは、まさにそれに対して警告しています。価値のある部分は、モデルが自力で信頼して発明できない、ドメイン固有の修正、エッジケース、ツール選択、規約です。正しいワークフローは、エージェントでタスクを一度解決し、機能するまで修正し、その後、その方法をSkillに抽出することです。

Skillは、ウィキのようにではなく、良い関数のようにスコープしてください。Anthropicは、Skillsは一貫した作業単位をカプセル化すべきであると述べています。狭すぎると、1つのタスクのために複数のスキルを重ねることを強制されます。広すぎると、エージェントはそれらを正確にアクティベートできません。ベストプラクティスガイドは、過度に包括的なスキルは、モデルが無関係な指示を追ってシグナルを失うため、助けよりも害を及ぼす可能性があると率直に述べています。

説明の品質は、表面的な問題ではありません。それはルーティングレイヤーです。AnthropicとAgent Skillsのドキュメントの両方が、description フィールドは、モデルがSkillを読み込むかどうかを決定するために使用する主なメカニズムであると述べています。良い説明は、Skillが何をするか、いつ使うべきか、ユーザーが実際に言及する可能性のあるトリガーフレーズやファイルタイプを述べます。悪い説明は、曖昧で、技術的すぎるか、ナンセンスにマッチするほど広範です。これは、FAQの質問「なぜClaude Skillがトリガーされないのか」に対する本当の答えです。通常、ルーターが悪く、モデルの問題ではありません。

対比は並べて見ると明確です：

悪い説明 — ルーティングが信頼できないほど曖昧：

• Helps with code review — すべてにマッチし、何も区別しない
• Useful for development tasks — 検索クエリよりも広い
• Assists with writing — ルーターではなく、単なるカテゴリラベル

良い説明 — 具体的なトリガー言語：

• Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.（セキュリティ問題、移行リスク、テスト不足についてプルリクエストをレビューします。PR、git diff、またはリリースクリティカルな変更をレビューする際に使用。）
• Generate a changelog from git log output. Use when preparing a release, writing release notes, or summarising commits since last tag.（git log出力から変更履歴を生成します。リリースの準備、リリースノート作成、または最後のタグ以降のコミット要約時に使用。）
• Scaffold a new Go HTTP handler with request validation and error middleware. Use when adding a new endpoint or route to a Go service.（リクエスト検証とエラーミドルウェアを備えた新しいGo HTTPハンドラーの骨格を作成します。Goサービスに新しいエンドポイントまたはルートを追加する際に使用。）

パターンは毎回同じです：Skillが何をするかを述べ、それをアクティベートすべき正確なユーザーフレーズを名乗り、必要に応じて関連するファイルタイプやツールを名乗ります。説明が一般的なGoogleクエリにマッチするならば、それは十分に具体的ではありません。

副作用があるワークフローは、手動にしてください。Claude Codeはそれを直接公開しています。disable-model-invocation: true はSkillをユーザー起動のみにします。これは、デプロイ、コミット、送信メッセージなどのアクションにAnthropicが推奨しています。user-invocable: false は逆の方向に働き、スラッシュメニューからSkillを隠しますが、Claudeが背景知識として使用できるようにします。これは、FAQトピック「スキルが自動ではなく手動であるべきなのはいつか」に1文で答えます：リスクには手動、安全な再現可能なガイダンスには自動です。

SKILL.md は、理解可能に保つために十分に小さく保ってください。Anthropicは、500行未満、約5,000トークンに保ち、詳細な資料は明示的な読み込み指示を伴う references/ または同様のファイルに移すことを推奨しています。「APIが200以外を返す場合は references/api-errors.md を読む」は良いパターンです。「参照を見てください」は怠惰です。Claude Codeはまた、レンダリングされたSkillをメッセージとして会話に注入し、後のターンでファイルを繰り返し読み込みません。コンテキスト圧縮後、トークン予算内で保持されるのは最近のSkill内容のみです。したがって、巨大なSkillsは単に醜いだけでなく、長いセッションでは脆いです。

良い SKILL.md は、非常に平らなままでいけます：

---
name: review-pr
description: Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
compatibility: Designed for Claude Code. Requires git and gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Review PR

コマンドを実行する前に references/checklist.md を読んでください。

1. diffと変更されたファイルを集める。
2. 正確性、セキュリティ、テストカバレッジの問題にフラグを立てる。
3. 重大度別にグループ化された調査結果をファイル参照付きで返す。
4. まず最小限の安全な修正を提案する。

決定性が雄弁さよりも重要である場合は、スクリプトを使用してください。Skillsスクリプトガイドは、ここで優れています。エージェント向けのスクリプトは、対話的なプロンプトを避け、--help 通过使用を文書化し、有用なエラーメッセージを出力し、stdoutにJSONやCSVなどの構造化出力を優先し、診断をstderrに送信し、リトライ安全な使用をサポートするべきであると述べています。また、環境に正しいパッケージがあることを前提とせず、使い捨てツールのバージョンをピン留めし、実行時の要件を SKILL.md または compatibility フィールドで明示的に説明することを推奨しています。

最小限ですが、正しいエージェント向けスクリプトは次のようなものです：

#!/usr/bin/env bash
# scripts/collect-diff.sh — called by review-pr skill
# Usage: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Structured output to stdout so the agent can parse it
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

3つのことが、これを経由して安全にします。set -euo pipefail は、スクリプトが静かに進むのではなく、失敗時に大きく終了することを保証します。stdoutへのJSONは、エージェントが推測せずに解析できる形式を提供します。診断はstderrに送信されるため、エージェントのstdoutストリームはクリーンなままです。これのどれもしつこいものではなく、すべて必要です。

1つの微妙なトラップは allowed-tools です。仕様では実験的であり、サポートは異なります。Claude Codeでは、Skillがアクティブな間に特定のツールを事前承認しますが、呼び出し可能なツールの宇宙を制限するものではなく、denyルールは依然としてClaude Codeの権限に属します。Claude Agent SDKでは、Anthropicは SKILL.md の allowed-tools frontmatterは適用されないと明示しており、SDKアプリはツールアクセスをメインの allowed_tools または allowedTools 設定で強制する必要があります。その違いを無視すると、SkillはCLIとSDK駆動の自動化で異なる挙動をします。

1つの高度なパターンは、盗む価値があります。ワークフローがメインスレッドをログ、ファイル検索、または長時間の調査出力で洪水にしようとする場合、Claude Codeは context: fork と Explore のような agent を使用して、フォークされたサブエージェント内でSkillを実行できます。Anthropicは、重い処理が分離されたコンテキストで発生し、メイン会話にサマリーが届く調査ワークフローのためにこれを示しています。深いコードベース探索では、メインセッションを汚染する巨大なインラインSkillよりも、はるかに良い設計です。

フォークされたSkillは、frontmatterで次のようになります：

---
name: explore-codebase
description: Deep exploration of an unfamiliar codebase. Use when onboarding to a new repo, auditing architecture, or mapping module dependencies.
context: fork
agent: Explore
compatibility: Requires Claude Code CLI.
---
# Explore Codebase

1. ディレクトリツリーを辿り、トップレベルのモジュールを要約する。
2. メインのエントリポイントとその責任を特定する。
3. パッケージ間の依存関係グラフをマッピングする。
4. 生のファイルリストではなく、構造化されたサマリーをメインセッションに返す。

重要な行は context: fork です。これがない場合、探索の出力は会話内にインラインで着地します。これがある場合、サブエージェントは独自のコンテキストウィンドウで実行し、サマリーを返します。探索自体が数千トークンを消費しうる大きなリポジトリでは、この違いが重要になります。

Claude Skillsのテスト：トリガー、正確性、ベースライン比較

Skillは、ハッピーパスのデモが一度機能したからといってテストされたわけではありません。Anthropicのガイドは、テストを3つのレイヤーに分解しています：Claude.aiでの手動テスト、Claude Codeでのスクリプトによるテスト、Skills APIを介したプログラムによるテスト。推奨される評価領域は、トリガー、機能的正確性、Skillなしのベースラインに対するパフォーマンスです。これはまた、FAQの質問「スキルが信頼できるかどうかをどうテストするか」に対する最善の答えでもあります。モデルが自信を持って聞こえたかどうかだけでなく、ルート選択、出力品質、効率をテストします。

公式の評価ガイダンスは、テストケースにクリーンな構造を与えます。各ケースには、現実的なユーザープロンプト、期待される出力の人間が読める説明、オプションの入力ファイルを含めるべきです。ドキュメントはそれらをSkillディレクトリ内の evals/evals.json に保存します。これは、独自のハーネスを構築する場合でも、合理的な慣習です。

フィクスチャファイルと、このようなしつこくない評価レイアウトを使用してください：

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR for security issues and missing tests",
      "expected_output": "Findings grouped by severity with file references and at least one test recommendation.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Summarise last week's commits",
      "expected_output": "The skill should not activate.",
      "files": []
    }
  ]
}

私のテストルールは、ほとんどのチームが使用するよりも厳格ですが、公式のガイダンスと整合しています。すべての本格的なSkillには、トリガーすべきクエリ、トリガーすべきでないクエリ、少なくとも1つのエッジケーステスト、Skillなしのベースライン比較が必要です。Anthropicの例では、「機能する」ことは「ワークフローを改善する」こととは同じではないため、ツール呼び出し、失敗したAPI呼び出し、明確化ループ、トークン使用量を、Skillあり/なしで比較しています。

Claude Agent SDKを介してテストする場合、配管（plumbing）を覚えておいてください。そこでは、Skillsはファイルシステム成果物であり、プログラムによる登録ではありません。Anthropicは、"Skill" ツールを有効にし、settingSources または setting_sources を通じて関連するファイルシステム設定を読み込む必要があると述べています。user または project を省略したり、cwd を誤った場所に向けたりすると、SDKはSkillを検出しません。Anthropicは、直接の発見チェックとして「利用可能なSkillsは何か？」と尋ねることを推奨しています。

また、実際に出荷するつもりのモデルとクライアントでテストしてください。オープンなAgent Skillsクイックスタートは、ツール使用の信頼性がモデル間で異なることを明示的に警告しており、一部のモデルは、Skillが意図するコマンドを実行するのではなく、直接回答する可能性があります。それは常にSkill設計の問題ではありません。時にはモデル選択の問題であり、テストマトリクスはそれを明らかにすべきです。

Claude Skillsのトラブルシューティング：一般的な失敗と修正

Skillが誤動作した場合、知能の前にパッケージングを疑ってください。最も一般的な失敗は、まだ退屈なもの（基本的なもの）です。

• Skillがまったく見つからない場合、ファイルが正確に SKILL.md と命名されているか、正しい大文字小文字で、正しいディレクトリ内にあるかを検証してください。Anthropicのトラブルシューティングガイドは、ファイル名の大文字小文字を明示的に指摘しており、そのClaude CodeとSDKのドキュメントは、最初のチェックとして .claude/skills/*/SKILL.md と ~/.claude/skills/*/SKILL.md に直接向けています。
• frontmatterが無効な場合、まずYAMLのデリミターと引用符を確認してください。Anthropicの例は、古典的なミスを示しています：--- の欠落、未閉じの引用符、スペースと大文字を含む無効な名前。スキル名は小文字でハイフン区切りであるべきです。
• Skillが存在するがトリガーされない場合、説明が通常は曖昧すぎます。Claude Code自身のトラブルシューティングは、ユーザーが自然に言う可能性のあるキーワードを含めること、"What skills are available?" と尋ねたときにSkillが表示されることを確認すること、説明に近づけて言い換えて試すことを述べています。AnthropicのPDFガイドは、優れた診断トリックを追加しています：ClaudeにそのSkillをいつ使用するかと尋ね、説明をどのように言い換えて返してくるか聞いてください。
• Skillが頻繁にトリガーされる場合、スコープを狭めてください。Anthropicは、説明をより具体的にし、ネガティブトリガーを追加し、明示的なコマンドでのみ実行したいワークフローに disable-model-invocation: true を使用することを推奨しています。過剰トリガーは、通常はルーティング言語が十分に指定されていないだけです。
• Skillが長いセッションで影響力を失うように見える場合、多くのスキルが存在する場合、Claude Codeカタログで説明が短縮されることができ、呼び出されたSkillsは圧縮後にトークン予算内で保持されることを覚えておいてください。Anthropicは、説明にキーワードを先頭から配置し、余分なテキストをトリミングし、特にClaude Codeについては、説明のリストが過度に圧縮されている場合、SLASH_COMMAND_TOOL_CHAR_BUDGET を調整することを推奨しています。
• 同梱のスクリプトがハングするか不規則に動作する場合、対話的な入力を期待しているかどうかを確認してください。スクリプトガイドは、エージェントが非対話的なシェルで実行されるため、TTYプロンプト、パスワードダイアログ、確認メニューは設計上のバグであると述べています。フラグ、環境変数、またはstdinを介して入力を受け入れ、失敗を明示的にしてください。
• SDKがSkillを見ない場合、allowed_tools に "Skill" が含まれているか、settingSources または setting_sources に user または project が含まれているか、cwd が実際に .claude/skills/ を含むディレクトリを指していることを確認してください。その設定なしでは、Markdownがどれだけ正しくても、Skillシステムは有効になりません。
• MCPバックエンドのSkillが読み込まれるがツール呼び出しが失敗する場合、Anthropicのトラブルシューティングチェックリストは合理的です：MCPサーバーが接続されていることを確認し、認証とスコープを確認し、SkillなしでMCPツールを直接テストし、それらが大小文字を区別するため、正確なツール名を確認してください。

退屈な真実は、良いClaude Skillsは良い運用エンジニアリングのように見えるということです。明確な名前。小さなファイル。明示的なトリガー。必要であれば決定論的なスクリプト。実際のテスト。あなたのSkillが鮮明なランブックのように読めるなら、エージェントは戦うチャンスがあります。ブレストのように読めるなら、あなたは単にフォルダの中に混沌を隠しただけです。