Claude Code・Codex のおすすめ Agent Skills：入れるべきスキル、インストール前の監査、新しいスキルが発動しない原因

Name

Soren Atelier

更新日 2026/11/15

結論：リポジトリを丸ごと入れず、スキルを数個だけ入れてください。ルールは次の 3 つです。

1. 用途で選ぶ。まずは obra/superpowers（15 スキル）のような小さなテキストだけのパックか、Jane Street の socratic-tutor のような単体スキルから始めます。google/skills（203 スキル）や NVIDIA/skills（452）のようなカタログは、その中の特定のスキルが必要になるまで触らないでください。
2. インストール前に読む。スキルは指示と任意のスクリプトのセットで、スクリプトはエージェントの権限で動きます。下のステップ 1 の監査スクリプトは、どのスキルがコードを同梱し、どのファイルを先に開くべきかを一覧にします。ファイルを読むだけです。
3. インストール後に一覧を確認する。Claude Code はスキルの名前と説明の一覧をモデルに渡しますが、この一覧には上限があります。すでに 98 個のスキルがあるマシンでは、新しく入れたスキルが名前のみで載り、モデルにはリクエストと照合する説明がありませんでした。/skill-doctor を実行し、skillOverrides で予算を空けるか、skillListingBudgetFraction で予算を増やします。

実測した範囲：この記事の数値はすべて、2026 年 11 月 15 日に取得した shallow clone と、macOS 上の Claude Code 2.1.325 から得たものです。監査スクリプト、claude plugin validate、/skill-doctor、デバッグログはすべて実行しました。その後モデルが自分でスキルを選ぶかどうかは検証していません。SkillSpector、npx skills インストーラー、Codex も検証していません。記事末尾近くの「実測とドキュメント由来」の表で両者を分けています。

スキルリポジトリ 10 個の比較

Agent Skills は SKILL.md ファイルを含むフォルダで、Claude Code、Codex などのエージェントが必要に応じて読み込みます。フォーマット自体を知りたい場合は、Codex vs Claude Code Skills がパス、frontmatter、1 つのスキルを両ツールで共有する方法を扱っています。このページは、他人が作ったスキルの選び方と入れ方の話です。

スキルリポジトリへの関心は 11 月上旬に急上昇しました。Jane Street は 11 月 3 日にスキル 1 個だけのリポジトリを公開し、Hacker News で 712 ポイントに達しました。GoogleChrome/modern-web-guidance は 11 月 10 日に 1.0.0 をリリースしました。anthropics/skills は 1 週間で約 6,200 スターを増やしました。

表は各リポジトリ内のすべての SKILL.md を数えたものです。「説明の文字数」は description テキストの合計の長さで、エージェントが毎ターン、すべてのスキルについて読み込む部分です。最後の列は、テストマシンで Claude Code が報告した 30,000 文字の一覧予算と比べた割合です。

目立つ点は 3 つあります。

• 規模は 2 桁違う。google/skills や NVIDIA/skills を全部入れると、一覧の予算を何倍も超えます。どちらの README も、スキル単位でインストールする方法を用意しています。NVIDIA は --skill、Google はインストーラーの選択プロンプトです。
• ほとんどのスキルはただの Markdown。782 スキルのうち 552 個はコードを一切同梱していません。同梱しているのはドキュメント、メディア、クラウド系のスキルに集中していて、決定的な処理をスクリプトが担当します。
• ツールの事前承認は 1 つのカタログ以外ではまれ。allowed-tools を宣言しているのは NVIDIA/skills の 126 スキルと google/skills の 2 スキルです。残り 8 つのリポジトリには 1 つもありません。

用途別の選び方

• obra/superpowers は一式そろった作業手法です。ブレインストーミング、計画の作成、実行、体系的なデバッグ、完了を宣言する前の検証まで含みます。コンテキストの面では、大きめのパックの中で最も安く済みます。
• addyosmani/agent-skills はエンジニアリングのチェックリスト集に近い内容です。コードレビュー、API 設計、CI、オブザーバビリティ、セキュリティ強化を扱います。説明が長めなので、25 スキルで Superpowers の約 4 倍のコストがかかります。
• mattpocock/skills は自分で呼び出す短いコマンド（/grill-me、/tdd、/to-spec）が中心です。in-progress のスキルが 8 個含まれています。
• anthropics/skills はリファレンス実装です。データを扱う人が欲しいのはたいてい xlsx、pdf、docx、pptx のスキルで、実際にファイルを生成するスクリプトが同梱されています。分析がノートブック中心なら、RunCell (opens in a new tab) のように Jupyter の中で動くエージェントが、これらのファイル系スキルでは届かない部分を補います。
• GoogleChrome/modern-web-guidance は、ガイドのインデックスを検索する CLI に支えられた 2 つのスキルです。エージェントに古いフロントエンドのパターンを使わせないことが狙いです。
• kajisho5/ffmpeg-skill は 107 個のコードファイルを持つ大きなスキル 1 個（同じものが 2 か所に置かれています）と、作者自身のプロジェクト用スキル 14 個（.claude/skills 配下）で構成されています。リポジトリをコピーするのではなく、付属のインストーラーで入れてください。

ステップ 1：インストール前にスキルリポジトリを監査する

スキルの指示はエージェントのコンテキストに入り、スクリプトはセッションが持つ権限のまま動きます。防御手段はリポジトリを先に読むことだけなので、読む作業を速くしましょう。

このスクリプトはフォルダを走査してすべての SKILL.md を見つけ、どのスキルがコードを同梱しているか、どのスキルに確認すべきパターンがあるかを出力します。Python 標準ライブラリだけを使い、スキャン対象のフォルダにあるものは一切実行しません。

#!/usr/bin/env python3
"""Read-only audit of SKILL.md folders. Runs nothing from the repo it scans."""
import os, re, sys
 
RISKY = {
    "pipe-to-shell": r"(curl|wget)[^\n|]*\|\s*(sudo\s+)?(ba|z)?sh",
    "reads-secrets": r"\.ssh/|\.aws/credentials|\.env\b|id_rsa|\.netrc|keychain",
    "sudo": r"\bsudo\s",
    "rm-rf": r"\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r",
    "skip-permissions": r"dangerously-skip-permissions|bypassPermissions|--yolo",
    "hidden-unicode": r"[\u200b\u200c\u200d\u2060\u202a-\u202e\U000e0000-\U000e007f]",
}
CODE = (".py", ".sh", ".js", ".mjs", ".ts", ".rb", ".ps1")
 
def frontmatter(text):
    m = re.match(r"^---\n(.*?)\n---\n?", text, re.S)
    if not m:
        return None, text
    fields, key = {}, None
    for line in m.group(1).splitlines():
        k = re.match(r"^([A-Za-z_-]+):\s*(.*)$", line)
        if k:
            key = k.group(1)
            fields[key] = k.group(2).strip().strip("\"'")
        elif key and line.startswith((" ", "\t")):
            fields[key] += " " + line.strip()
    return fields, text[m.end():]
 
def audit(root):
    rows = []
    for folder, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in (".git", "node_modules")]
        if "SKILL.md" not in files:
            continue
        text = open(os.path.join(folder, "SKILL.md"), encoding="utf-8", errors="replace").read()
        fields, body = frontmatter(text)
        everything, code_files = text, 0
        for sub, _, names in os.walk(folder):
            for n in names:
                if n.endswith(CODE):
                    code_files += 1
                if n.endswith(CODE + (".md",)) and n != "SKILL.md":
                    try:
                        everything += open(os.path.join(sub, n), encoding="utf-8", errors="replace").read()
                    except OSError:
                        pass
        flags = [name for name, pat in RISKY.items() if re.search(pat, everything)]
        if fields is None:
            flags.append("no-frontmatter")
            fields = {}
        if fields.get("allowed-tools"):
            flags.append("allowed-tools")
        if "hooks" in fields:
            flags.append("hooks")
        if re.search(r"!`[^`]+`|```!", body):
            flags.append("shell-injection-block")
        desc = (fields.get("description", "") + " " + fields.get("when_to_use", "")).strip()
        rows.append((os.path.relpath(folder, root), len(desc), len(body), code_files, flags))
    return rows
 
if __name__ == "__main__":
    rows = audit(sys.argv[1])
    listing = sum(d for _, d, _, _, _ in rows)
    print(f"{len(rows)} skills, {listing:,} description chars (~{listing // 4:,} tokens if all are listed)")
    print(f"{sum(1 for r in rows if r[3])} skills ship code files, {sum(r[3] for r in rows)} code files in total")
    for path, desc, body, code, flags in sorted(rows, key=lambda r: (-len(r[4]), r[0])):
        if flags or "-v" in sys.argv:
            print(f"  {path}: desc={desc} body={body} code={code} flags={','.join(flags) or '-'}")

リポジトリをプロジェクトの外にクローンし、スクリプトにそのパスを渡します。

git clone --depth 1 https://github.com/obra/superpowers /tmp/superpowers
python3 audit_skills.py /tmp/superpowers

11 月 15 日時点の Superpowers の出力です。

15 skills, 2,317 description chars (~579 tokens if all are listed)
3 skills ship code files, 6 code files in total
  skills/brainstorming: desc=213 body=14933 code=3 flags=rm-rf
  skills/subagent-driven-development: desc=85 body=19484 code=0 flags=rm-rf
  skills/systematic-debugging: desc=91 body=9366 code=2 flags=reads-secrets

フラグの読み方

フラグは「このファイルを開いて確認する」という意味で、「このスキルは悪意がある」という意味ではありません。この 10 リポジトリで手作業で確認したフラグは、すべて無害でした。Superpowers の rm-rf は、自分の一時フォルダを片付けるスクリプト内の rm -rf "$SESSION_DIR" です。ffmpeg-skill の hidden-unicode は、ヒンディー語の合字についての注記に含まれるゼロ幅接合子です。reads-secrets は .env に触れているだけで反応し、コミットするなという助言にも反応します。

Claude Code では最後の 3 つが最も重要です。allowed-tools は、スキルを呼び出したターンの間、確認なしでツールを許可します。hooks のエントリはセッションが終わるまで動き続けます。!`command` ブロックはスキルが読み込まれた時点で実行されます。

追加のチェック 2 つ

Claude Code は frontmatter を検証できます。インストール済みの 91 スキルが入ったフォルダでは問題なく通りました。プラグインとしてパッケージされていないリポジトリでは No manifest found で失敗し、そのリポジトリがコピー専用だと分かります。

claude plugin validate .claude/skills

より深くスキャンするなら、NVIDIA の SkillSpector (opens in a new tab) が専用スキャナーで、71 個のパターンと 0〜100 のリスクスコアを備えています。README はクイックパスとして次を示していますが、この記事では実行していません。

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector scan ./my-skill/ --no-llm

ステップ 2：必要なものだけインストールする

フォルダを 1 つコピーする方法が最も仕組みが単純で、ここで実測したのもこの方法です。

git clone --depth 1 https://github.com/janestreet/agent_skills /tmp/agent_skills
mkdir -p .claude/skills
cp -R /tmp/agent_skills/socratic-tutor .claude/skills/

コピー先によって、スキルが読み込まれる範囲が決まります。

試しに使うものはプロジェクトフォルダに置いてください。他のセッションにスキルが入り込まず、フォルダを消せば削除できます。

残り 2 つの方法は各プロジェクトの README に基づくもので、ここでは実行していません。

• プラグインはパック全体をインストールし、更新は /plugin から行います。たとえば /plugin marketplace add anthropics/skills の後に /plugin install document-skills@anthropic-agent-skills を実行します。Superpowers は /plugin install superpowers@claude-plugins-official です。
• Vercel Labs の skills CLI は、多数のエージェント向けにファイルをまとめてプロジェクトへコピーします：npx skills add addyosmani/agent-skills --skill test-driven-development -a claude-code。先に中身を見たいときは --list を付けます。

Claude Code のドキュメントにある注意点が 1 つあります。skillOverrides はプラグインのスキルには適用されません。プラグインのパックが大きすぎる場合は、個々のスキルではなくプラグインごと無効にします。

ステップ 3：新しいスキルが本当に一覧に載っているか確認する

このステップでは、「インストールしたのに発動しない」原因のうち、エラーが一切出ないものを見つけます。

Claude Code は、すべてのスキルの名前と説明の一覧をモデルに渡します。この一覧には予算があり、デフォルトではコンテキストウィンドウの 1% です。あふれると、Claude Code は名前をすべて残したまま、使用頻度の低いスキルから順に説明を落とします。入れたばかりのスキルの使用回数は 0 です。この仕組みは Claude Code ドキュメントの「Skill descriptions are cut short」（スキルの説明が切り詰められる） (opens in a new tab)で説明されています。以下の数値は、それが実際にどう見えるかを示すものです。

個人スキル 84 個とプラグインスキル 14 個がすでにあるマシンでは、次のようになりました。新しいスキルを 1 個コピーした後、デバッグログにはこう出ました。

[WARN] Skill listing over budget: 112 skills, 37491 chars > 30000 budget — descriptions will be truncated.

そして /skill-doctor では、新しいスキルが名前のみで載っていました。

ただし、コストが < 20 というだけでは証拠になりません。説明が 1 行しかないスキルも 20 未満になるからです。説明の長さと見比べてください。以下の件数には、判別できるだけの長さの説明を持つスキルだけを含めています。

スキルを増やすと、他のスキルにも影響が広がりました。プロジェクトスキルを 91 個入れた状態では、76 個が一覧に載り、そのうち 70 個は 80 文字以上の説明を失っていました。289 個では、説明を失った「個人」スキルが 6 個から 39 個に増えました。新しく入ったスキルが、それまで機能していたスキルの説明を押し出したのです。

チェックを実行する

/skill-doctor は、スキルごとに 1 行ずつ一覧上のコストを表示します。Claude Code 2.1.252 以降が必要で、-p モードでも動きます。

claude -p "/skill-doctor"

予算超過の警告そのものを見るには、デバッグログを書き出して検索します。

claude --debug-file /tmp/cc-debug.log -p "hello"
grep "Skill listing over budget" /tmp/cc-debug.log

直し方

まず使っていないものをオフにします。プロジェクト単位なら .claude/settings.json、すべてのプロジェクトなら ~/.claude/settings.json に書きます。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

"name-only" は、スキルを /name で呼び出せるまま残し、説明だけを一覧から外します。"off" は完全に隠します。対話セッションでは /skills から同じ設定を書き込めます。行の上で Space を押して状態を切り替え、Esc で保存します。

本当に全部使っているなら、代わりに予算を増やします。毎ターン、その分のコンテキストを消費します。

{
  "skillListingBudgetFraction": 0.02
}

Codex にも同じ仕組みがあり、数値が違います。ドキュメントによると、最初のスキル一覧はコンテキストウィンドウの最大 2%、ウィンドウが不明な場合は 8,000 文字までを使い、まず説明を短縮し、警告を出したうえでスキルを一覧から省くことがあります。skills.max_context_tokens で予算を変更でき、~/.codex/config.toml に enabled = false を指定した [[skills.config]] エントリを書くとスキルを 1 個無効にできます。

ステップ 4：スキルを無人で実行させる

11 月 13 日リリースの Claude Code 2.1.325 では、スケジュール実行に影響する挙動が 1 つ変わりました。スケジュールされたタスクと /loop は、allowed-tools またはフックを宣言したスキルを実行する前に確認を求めるようになりました。そうしたスキルをプロンプトなしで動かすには、名前を指定して許可します。

{
  "permissions": {
    "allow": ["Skill(release-notes)"]
  }
}

逆も可能です。Skill(deploy *) のような deny ルールはモデルによるスキルの呼び出しを止め、引数なしの Skill を deny するとすべてのスキルがオフになります。どちらも Claude Code のドキュメントに基づく内容です。リポジトリにコミットしておく価値のあるその他の権限設定は、Claude Code の権限設定を強化するで扱っています。

ステップ 5：スキルを削除する

• コピーしたスキル：.claude/skills/ または .agents/skills/ 配下のフォルダを削除します。
• プラグインのスキル：/plugin uninstall <plugin>@<marketplace> を実行するか、/plugin で無効にします。
• 残したまま自動使用だけ止める：skillOverrides で "name-only" か "off" に設定します。ファイルが自分のものなら、frontmatter に disable-model-invocation: true を追加する方法もあります。

実測とドキュメント由来

30,000 文字という予算は、1 台のマシンが報告した値です。実際の値はモデルのコンテキストウィンドウによって変わるので、割合の列を当てにする前に自分のデバッグログを確認してください。

FAQ

Claude Code で最初に入れるべき Agent Skills はどれですか？

小さく始めてください。obra/superpowers は計画、テスト、デバッグ、レビューの一連のワークフローを 15 スキルで提供します。addyosmani/agent-skills は 25 個のエンジニアリングチェックリストを追加します。スプレッドシート、PDF、スライドには anthropics/skills の document-skills プラグインを入れます。大きなカタログは丸ごとではなく、スキルを 1 個ずつ入れてください。

Claude Code の新しいスキルが発動しないのはなぜですか？

スキルが多いマシンでは、おそらく一覧が予算を超えていて、新しいスキルは名前のみで載っています。/skill-doctor を実行してください。説明が長いスキルで context cost が 20 未満なら、説明は落とされています。使わないスキルを skillOverrides でオフにするか、skillListingBudgetFraction を上げます。

インストール前にスキルが安全かどうかを確認するには？

プロジェクトの外にクローンして読みます。同梱スクリプト、allowed-tools、hooks、!`command` ブロックを探してください。上の監査スクリプトは、何も実行せずにすべての SKILL.md についてそれらを一覧にします。

Claude Code ではスキルをいくつ入れると多すぎますか？

個数ではなく説明の長さで決まります。anthropics/skills の 20 スキルは、30,000 文字の予算のうち約 9,500 文字を使います。google/skills を全部入れると約 107,600 文字が必要です。

/skill-doctor は何をするコマンドですか？

読み込まれたすべてのスキルについて、提供元、一覧上のコスト、7 日間のトークン使用量、呼び出し回数を表示し、一度も使われていないものにフラグを付けます。Claude Code 2.1.252 以降が必要です。

Claude Code と Codex の両方で使うには、スキルをどこに置けばいいですか？

Claude Code は .claude/skills/、Codex は .agents/skills/ で、プロジェクト内かホームディレクトリに置きます。コピーは 1 つだけ持ち、もう一方にはシンボリックリンクを張ります。

スキルを削除せずに無効化できますか？

できます。Claude Code では設定の skillOverrides、Codex では enabled = false を指定した [[skills.config]] を使います。プラグインのスキルは /plugin で管理します。

Claude Code 2.1.325 でスケジュールタスクがスキル実行前に確認を求めるのはなぜですか？

スケジュールされたタスクと /loop は、allowed-tools またはフックを宣言したスキルを実行する前に確認を求めるようになりました。permissions.allow に Skill(name) を追加してください。

参考資料

• Extend Claude with skills (opens in a new tab) と settings reference (opens in a new tab)、Claude Code ドキュメント
• Claude Code changelog (opens in a new tab)、バージョン 2.1.325
• Build skills (opens in a new tab)、Codex ドキュメント
• Agent Skills specification (opens in a new tab)
• vercel-labs/skills (opens in a new tab) と NVIDIA/SkillSpector (opens in a new tab) の README
• Hacker News の Socratic Tutor スレッド (opens in a new tab)

関連ガイド

• Codex vs Claude Code Skills：セットアップ、設定、両方のエージェントでスキルを共有する方法
• Claude Code の権限設定を強化する：リポジトリ外への書き込みをブロック、プロンプト待ちを拒否に、settings.local.json を監査
• Claude Code Mods 入門：最初の Mod の作り方・テスト・導入手順と、コミュニティ実例 15 選
• Claude CodeのAGENTS.md設定と移行: 4つの読み込みモードとCLAUDE.mdとの違い
• OpenCodeの使い方ガイド: 始め方、実践Tips、Oh My OpenCodeとの使い分け