◉CLAUDE LABEN
●2.1.278 — auto モードの分類器が Claude API・Enterprise・Bedrock / Vertex / Foundry でサーバー側の既定になりました。分類器の分は課金されず、/status に Auto mode server の行が増えています●TASKOUT — TaskOutput ツールが削除されました。taskOutputMaxChars と TASK_MAX_OUTPUT_LENGTH は無効になり、バックグラウンドの出力は Read で読む形に一本化されています●10/07 — 管理構成キーの旧い綴りの受付は10月7日 正午 PT までです。残り17日で、締切を過ぎた設定は書き直すまでそのコネクタが使えなくなります●BUNPANIC — 更新で入った版が、起動しただけで落ちるという報告が出ています。同じ機械で前の版は動くとのことで、環境ではなく版の側が疑われています●NEW — Cowork と Claude Code のどちらに置くかを、承認の境界で決めた記録です●SONNET4.5 — 廃止表に並ぶ日付は「それより前には終わらない下限」です。Sonnet 4.5 は今も有効で、非推奨の告知は出ていません●2.1.278 — auto モードの分類器が Claude API・Enterprise・Bedrock / Vertex / Foundry でサーバー側の既定になりました。分類器の分は課金されず、/status に Auto mode server の行が増えています●TASKOUT — TaskOutput ツールが削除されました。taskOutputMaxChars と TASK_MAX_OUTPUT_LENGTH は無効になり、バックグラウンドの出力は Read で読む形に一本化されています●10/07 — 管理構成キーの旧い綴りの受付は10月7日 正午 PT までです。残り17日で、締切を過ぎた設定は書き直すまでそのコネクタが使えなくなります●BUNPANIC — 更新で入った版が、起動しただけで落ちるという報告が出ています。同じ機械で前の版は動くとのことで、環境ではなく版の側が疑われています●NEW — Cowork と Claude Code のどちらに置くかを、承認の境界で決めた記録です●SONNET4.5 — 廃止表に並ぶ日付は「それより前には終わらない下限」です。Sonnet 4.5 は今も有効で、非推奨の告知は出ていません
記事一覧/Claude Code
⟐ Claude Code/2026-08-06上級

呼んだはずのスキルが何も返さない — 起動前に名前の解決順序を確定させる

端末の組み込みコマンドと同名のスキルは、非対話セッションで呼び出しが解決されないことがあります。実効名の表を起動前に作る preflight を書いて走らせ、検査器自身が取りこぼしていた2件までを実測で洗い出した記録です。

Claude Code256スキル設計2無人実行6preflight4名前空間3
✦ プレミアム記事

深夜に回しているスケジュール実行のログを朝に開いたら、進行の記録がほとんど残っていませんでした。

失敗した形跡はありません。エラーも、スタックトレースも、タイムアウトの記録も残っていませんでした。ただ、呼んだはずの手順が一度も動いていないのです。

原因にたどり着くまでに、私は権限設定とネットワークの許可リストを先に疑いました。どちらも無実でした。実際に起きていたのは、もっと素朴なことです。プラグインから配布していたスキルの名前が、端末の組み込みコマンドと衝突していました。

対話セッションでは、同じ名前を打つと組み込み側が応答します。ですから「動いている」ように見えます。非対話セッションでは、その呼び出しが誰にも解決されないまま落ちていました。

この不具合そのものは 2026年8月6日付の更新で修正されています。ただ、修正されたのは特定の症状であって、構造は残ります。呼び出し名は複数のソースから供給され、実効名は解決順序で決まります。その順序を知らないまま名前を付ければ、また同じ形で静かに壊れます。

そこで、実効名の表を起動前に作る道具を書きました。書いて、走らせて、その検査器自身が取りこぼしていたものを見つけました。

呼び出し名は一覧ではなく解決順序で決まる

スキルの供給元は一つではありません。プロジェクト直下、ユーザーのホーム、プラグイン経由の配布。組織で運用していれば、そこに管理者が配る束が加わります。

私たちはこれを「使えるスキルの一覧」として捉えがちです。実際には一覧ではなく、同じ名前空間に複数のソースが書き込む多重定義です。

供給元置き場所誰が変更するか変更に気づけるか
組み込みコマンド端末本体ベンダー更新履歴を読めば
プロジェクトリポジトリ内自分・チーム差分に出る
ユーザーホーム配下自分版管理外なら気づけない
プラグイン導入したプラグイン配布元ほぼ気づけない

厄介なのは下の2行です。ホーム配下のスキルはリポジトリの差分に出ません。プラグインが提供するスキルは、配布元が新しい名前を追加した瞬間に、こちらの断りなく名前空間へ入ってきます。

つまり、自分の書いたスキルが今日も同じ名前で呼べるかどうかは、自分だけでは決められません。

ここに組み込みコマンドが加わります。組み込み側はいちばん強く、そしていちばん入れ替わりが速い場所でもあります。8月に入ってからだけでも、手動で起動できるスキルの口が増えています。昨日まで空いていた名前が、今日は埋まっていることもあります。名前空間とは、そういう性質のものなのだと思います。

対話と非対話で挙動が分かれる理由

対話セッションでは、入力した名前は端末の入力層をまず通ります。組み込みコマンドと一致すれば、そこで処理が終わります。人間が打っている以上、応答がないことにはすぐ気づきます。

非対話セッションには、その入力層がありません。呼び出しはエージェント側の解決に委ねられます。ここで名前が組み込み側に予約されていると、エージェントの持つスキル表とベンダーの予約語がずれ、呼び出しが宙に浮きます。

そして無人実行には、宙に浮いたことを咎める人がいません。

私自身、この構造を理解するまで「権限が足りていないはずだ」という筋で3時間ほど調べていました。権限の問題であれば拒否の記録が残ります。何も記録が残っていないという事実こそが、権限ではないという手がかりだったのですが、そこに気づくのが遅れました。

実効名の表を起動前に作る

必要なのは、実行のたびに「この名前を呼んだら、どのファイルが動くのか」を確定させることです。

方針は3つに絞りました。

  1. すべての供給元を走査し、実効名を1つの表に集約すること
  2. 組み込みコマンドと衝突する名前は、警告ではなく停止として扱うこと
  3. 走査できなかった供給元があれば、それ自体を失敗として報告すること

3つ目が後で効いてきます。

以下がそのまま動く実装です。Node.js の標準モジュールだけで完結させました。依存を足すと、無人実行の環境で入っていない事故が起きるためです。

#!/usr/bin/env node
// name-preflight.mjs — スキルの「呼び出し名」を起動前に解決し、衝突を落とす
import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
import { join, basename } from "node:path";
 
// 端末組み込みコマンド。自分の環境の /help 出力から起こし、CI では固定リストとして版管理する
const BUILTIN = new Set([
  "help", "clear", "compact", "config", "cost", "doctor", "exit",
  "init", "login", "logout", "mcp", "memory", "model", "permissions",
  "release-notes", "resume", "review", "rewind", "status", "vim",
]);
 
// 優先度: 数字が小さいほど先に解決される想定。実環境の観測結果で必ず上書きすること
const SOURCES = [
  { id: "project", rank: 1, root: ".claude/skills" },
  { id: "user",    rank: 2, root: join(process.env.HOME ?? "", ".claude/skills") },
  { id: "plugin",  rank: 3, root: ".claude/plugins", nested: true },
];
 
const missingRoots = [];
 
function readName(dir) {
  const f = join(dir, "SKILL.md");
  if (!existsSync(f)) return null;
  const head = readFileSync(f, "utf8").split(/\n---\s*\n/)[0];
  const m = head.match(/^name:\s*(.+)$/m);
  return (m ? m[1] : basename(dir)).trim().replace(/^["']|["']$/g, "");
}
 
function scanFlat(root, source, owner) {
  if (!existsSync(root)) { missingRoots.push(`${source}:${root}`); return []; }
  return readdirSync(root)
    .map((e) => join(root, e))
    .filter((p) => statSync(p).isDirectory())
    .map((p) => ({ name: readName(p), source, owner, path: p }))
    .filter((r) => r.name);
}
 
function collect() {
  const out = [];
  for (const s of SOURCES) {
    if (!s.nested) { out.push(...scanFlat(s.root, s.id, s.id)); continue; }
    if (!existsSync(s.root)) { missingRoots.push(`${s.id}:${s.root}`); continue; }
    for (const plug of readdirSync(s.root)) {
      out.push(...scanFlat(join(s.root, plug, "skills"), s.id, plug));
    }
  }
  return out;
}
 
function resolve(entries) {
  const rank = Object.fromEntries(SOURCES.map((s) => [s.id, s.rank]));
  const byName = new Map();
  for (const e of entries) {
    const list = byName.get(e.name) ?? [];
    list.push(e);
    byName.set(e.name, list);
  }
  const findings = [];
  for (const [name, list] of byName) {
    list.sort((a, b) => rank[a.source] - rank[b.source]);
    const winner = list[0];
    if (BUILTIN.has(name)) {
      findings.push({
        level: "block", name,
        reason: "端末組み込みコマンドと同名。非対話セッションでは呼び出しが解決されない可能性がある",
        effective: "builtin", losers: list,
      });
      continue;
    }
    if (list.length > 1) {
      findings.push({
        level: "warn", name,
        reason: `同名スキルが ${list.length} 件。${winner.source}(${winner.owner}) が優先される`,
        effective: `${winner.source}:${winner.owner}`, losers: list.slice(1),
      });
    }
  }
  return { total: entries.length, unique: byName.size, findings };
}
 
const t0 = process.hrtime.bigint();
const r = resolve(collect());
const ms = Number(process.hrtime.bigint() - t0) / 1e6;
 
const blocks = r.findings.filter((f) => f.level === "block");
const warns  = r.findings.filter((f) => f.level === "warn");
for (const m of missingRoots) console.log(`[GAP] 走査対象が存在しません: ${m}`);
console.log(`scanned=${r.total} unique=${r.unique} block=${blocks.length} warn=${warns.length} in ${ms.toFixed(1)}ms`);
for (const f of [...blocks, ...warns]) {
  console.log(`[${f.level.toUpperCase()}] /${f.name} -> ${f.effective}`);
  console.log(`        ${f.reason}`);
  for (const l of f.losers) console.log(`        shadowed: ${l.source}:${l.owner} (${l.path})`);
}
process.exit(blocks.length > 0 || missingRoots.length > 0 ? 1 : 0);

BUILTIN を定数で持たせている点には理由があります。組み込みコマンドの一覧をその場で問い合わせて取ると、問い合わせ自体が失敗したときに「衝突ゼロ」という誤った安心を返してしまいます。手元で確認した一覧を版管理に置き、更新のたびに差分を目で見る——この鈍い運用のほうが、無人実行では信頼できます。

rank の並びも同様です。優先順位を推測で決め打ちしても、実環境がその通りとは限りません。ここは自分の環境で意図的に衝突を作り、どちらが応答したかを観測して上書きしてください。私が意味を持たせているのは「順序が固定されていて、その順序が明示されている」という一点です。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦組み込みコマンドと同名のスキルを起動前に落とす preflight（Node.js 約90行・そのまま動きます）と、10件のスキルツリーでの実測出力
✦運用一か月で判明した警報側の欠陥2件（commands-only プラグインで恒常的に exit 1・壊れたシンボリックリンクで検査器ごとクラッシュ）と、終了コードを 0/2/3 に分ける修正版
✦ディレクトリ名で数えると1件、実効名で数えると2件になる理由と、500スキル18ms という走査コストの実測
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥2,480 の永久アクセス
メンバーシップを見る →

関連記事

⟐ Claude Code2026-08-24
同じスキルを二か所に置いていたら、片方だけ中身が痩せていました
同名のスキルが二つのスコープに存在していました。SKILL.md は sha256 まで一致しているのに、片方には本文が名指ししているファイルが入っていません。66本を走査して欠落2件に絞るまでに検出器を三度書き直した記録です。
⟐ Claude Code2026-07-18
宣言したMCPサーバーが一覧から消えていた — 名前空間をベンダーと共有する前提で設定を組み直す
MCPサーバー名がベンダーに予約され、自分の .mcp.json の宣言が黙って無効になる。無人実行で気づけないこの欠落を、宣言と実体を突き合わせる preflight と接頭辞規約で落とす設計をまとめました。
⟐ Claude Code2026-09-12
巡回タスクが朝まで返らなかった原因は、WebFetch の待ち時間に上限がなかったことでした
Claude Code v2.1.268 で WebFetch に 300 秒の期限が付きました。応答を閉じないサーバーに当たると無人実行がどこで止まるのか、CLAUDE_CODE_WEBFETCH_DEADLINE_MS の 0 がなぜ「待たない」ではないのかを、手元で再現できる形で整理します。
📚RECOMMENDED BOOKS
大規模言語モデル入門
山田育矢
LLM開発
生成AIプロンプトエンジニアリング入門
我妻幸長
プロンプト
Claude CodeによるAI駆動開発入門
平川知秀
AI駆動開発
※ アフィリエイトリンクを含みます