常駐の Mac で、claude -p を無人で呼ぶ文章生成のジョブを動かしています。1つのジョブが3つの段(入力から題材を選ぶ・下書きする・照合する)で claude -p を呼び、どの段も、リポジトリに置いたスキル(.claude/skills/<スキル名>/SKILL.md)を /<スキル名> <入力フォルダ> の形で指定していました。
2026年10月2日の 02:30、選ぶ段が1回落ちました。返ってきたのは成果物ではなく、「そのコマンドは無い」という趣旨の答えでした(次の再試行で回復)。調べると、この呼び出しの構成(--restricted ほか)では /<スキル名> がスラッシュコマンドとして解決されず、スキルとして展開されないまま、フォールバックの説明を添えた普通の依頼としてモデルに渡されていました。9月26日〜10月2日にこの常駐 Mac で走った40回は、すべてこの状態でした。
それでも、多くの回は成果物を返していました。Claude Code は「そのコマンドはこのセッションに無いので、手持ちのツールで作業せよ」とモデルに伝え、モデルはリポジトリを検索して SKILL.md を見つけ、読んでから作業していたからです。
この記事は、その仕組みと、スキルの本文を直接渡す形に変えた記録です。以前の記事は無人の claude -p の権限の話でしたが、今回はスキルが展開されたかどうかの話です。
前提と限定
- 常駐 Mac での40回と10月2日の失敗は、当時のコミットと運用メモの記録です。常駐 Mac の Claude Code の版は記録していません(macOS は9月28日に 26.6.2 から 27.0 へ)
- ノートPC(macOS 27 系)にも同じ形の呼び出しのセッション記録(
~/.claude/projects/の下の.jsonl)が残っていたので、10月25日に数えました。下の数字の多くはこちらです(実行の目的は確かめていません)。版は 9月26日〜28日が 2.1.283、9月30日が 2.1.285、直した後の形は 10月2日が 2.1.287、10月5日が 2.1.289 でした - 当時の記録は原因を
--restrictedとしていますが、それだけを変えた実験はしていません。言えるのは「記録した構成では、対象のスキルがスラッシュコマンドとして解決されなかった」までです - 執筆時の版は 2.1.310 です。2.1.310 で同じ構成のときに対象のスキルが解決されるかは測っていません(執筆の作業では
claude -pを走らせない決まりのため)。--restrictedの説明は 2.1.310 の実行ファイル内の--help用の文字列で読み、公式ドキュメントでスキルの扱いは確かめていません - 1つの環境の記録です。ユーザー単位やプラグインのスキルがどうなるかは確かめていません
- 私はエンジニアではなく、調査と修正も AI が行い、別の AI(Codex)にレビューさせました
呼び方と、--restricted を付けた理由
直す前の呼び方は、概ねこうでした(実際は Python から引数の配列で渡し、外側を macOS の sandbox-exec で包み、環境変数も最小限にしています)。
claude -p "/<スキル名> /tmp/bundle-xxxx" --output-format json \
--restricted --add-dir /tmp/bundle-xxxx \
--tools Read,Grep,Glob --allowed-tools Read,Grep,Glob \
--strict-mcp-config --permission-mode dontAsk \
--disallowed-tools "<機微な場所への Read/Grep/Glob を拒否するルール>"
モデルは読むだけで、書くのも配送するのも Python 側です。起動時のカレントディレクトリはリポジトリ、入力フォルダは /tmp/bundle-xxxx(--add-dir で足す)。9月26日のレビューの指摘で --restricted を足し、コマンドを実行させないことと、ファイル系のツールが届く範囲をこの2つ(作業ディレクトリ)に寄せることを狙いました。機微なファイルは、さらに拒否ルールと外側の sandbox-exec で塞いでいます。実測で確かめたのは、~/.config の下の認証ファイル1つが「作業ディレクトリの外」として読めないことです。
2.1.310 の --help の説明文は次のとおりです(実行ファイルの中の文字列で確認)。
Restricted mode: removes the built-in tools that run commands or code (…) unless --tools names them, and ignores user, project and local settings files (managed settings and --settings still apply; …). Also confines the file tools to the working directories (--add-dir included), …
スキルの語はありません。そして私自身、9月27日の最初のコードのコメントに「ユーザー/プロジェクト設定を読まず」と書いていたのに、それが /<スキル名> という呼び方に効きうることには結びつけていませんでした。
何が起きていたか
コマンドとして展開されず、「手持ちのツールでやれ」と渡されていた
ノートPCのセッション記録には、直す前の形で呼んだ回のたびに、次の型の記録が1件ずつ残っていました(スキル名は伏せています)。
{"type": "attachment", "version": "2.1.285", "entrypoint": "sdk-cli",
"attachment": {"type": "unknown_command_fallback",
"commandName": "<スキル名>",
"availableCommandNames": ["dataviz", "update-config", "code-review", "simplify", "…(計12個)"],
"availableCommandCount": 47}}
一覧に名前が出ていた12個は、どれも Claude Code に組み込みのコマンドで、対象のスキルは含まれていません(残り35個の名前は記録に無く、ほかのスキルが載っていたかは分かりません)。
このとき、モデルには次の文面が渡されていました。2.1.283 と 2.1.285 のセッション記録に残っていたもので、2.1.310 の実行ファイルにも同じ文面を組み立てるコードが入っています。
The user's message starts with the slash command /<スキル名>, but no command with that name is available in this session, so it did not run. Slash commands available in this session: /dataviz, /update-config, … and 35 more. Treat the message as a plain request and do the task with the tools you have. If the task needs that command, tell the user it is not installed in this session. …
「コマンドは実行されなかった。普通の依頼として、手持ちのツールで作業せよ」。エラーにはならず、モデルに続きが任されます。
モデルは探し当てた(156回中154回)
ノートPCに残っていた直す前の形の呼び出しは156回(9月26日〜30日)です。そのうち154回で、モデルが SKILL.md を自分で探し当てて読む記録がありました。典型的な流れはこうです。
Glob **/* (入力フォルダの一覧)
Grep "<スキル名>" → Found 7 files(SKILL.md のほか、設計メモや作業記録にも名前が出てくる)
Read .claude/skills/<スキル名>/SKILL.md
Read <入力フォルダ>/meta.json
156回のうち125回は、SKILL.md を読む前にスキル名(またはその一部)で Grep していました。SKILL.md を読むまでのツール呼び出しは2〜9回(中央値3回)です。--restricted でもファイル系のツールは作業ディレクトリ(起動時のカレントディレクトリと、--add-dir で足した入力フォルダ)の中なら使え、カレントディレクトリはリポジトリでした。だから見つかりました。
外れた2回
1回目(9月30日 19:01・2.1.285・選ぶ段)。最初の検索が Glob **/*<スキル名>* で、結果は No files found でした。モデルは入力フォルダを一覧したあと、こう答えて終わっています。
I couldn't run
/<スキル名>because that command isn't installed in this session. There's also no<スキル名>skill or command definition anywhere in (リポジトリ), so I have no instructions for what it's supposed to do.
SKILL.md はリポジトリにありました。スキル名が入っているのはディレクトリ名で、ファイル名は SKILL.md だから当たらなかった、というのが記録から読める説明です(Glob の仕様は文書で確かめていません)。10月2日 02:30 の常駐 Mac の失敗も、記録では同じ Glob の空振りでした。
11秒後に始まった次の回(別の入力フォルダ)は SKILL.md を見つけて進んでいて、この9月30日の回のことは、修正のコミットにも運用メモにも書かれていません。
2回目(9月30日 19:29・2.1.285・下書きする段)。こちらは SKILL.md を読まないまま、入力フォルダの中のファイルだけを手がかりに作業し、成果物を返していました。
コマンド
/<スキル名>はこのセッションには入っていないので、同じ作業を手で行いました。
手順書を読まずに作った成果物です。後段でどう扱われたかは追えていません。
なぜ1週間気づかなかったか
確認していた成果物と照合の結果からは、呼び方の問題に気づけなかったからです。常駐 Mac での最初の試し運転も初回の本番も照合に合格し、設計のレビュー(別系統のモデルで4巡、観点を分けて5本)も通ったまま本番に入りました。
成功した回の結果の JSON(--output-format json)の result は成果物に見え、私が監視していた項目(成果物・照合の合否・終了コード)では、フォールバックを判別できませんでした。フォールバックの型の記録を確かめられたのは、セッション記録の中です(ほかの出力形式に出るかは確かめていません)。
振り返ると、手がかりはもっと前に出ていました。9月26日の 23:55 ごろにノートPCで走らせた probe の1つは「<スキル名> というスキルがあなたのスキル一覧にあるか yes/no だけで答えて」で、答えは2回とも no でした(同じ数分の probe の1つのエラー文に --restricted confines the file tools… と出ているので、--restricted 付きと判断)。自己申告なので、これだけで状態は決められません。ただ、直後に /<スキル名> の形で試した3回は、どれもフォールバックの記録を残しながら SKILL.md を探し当てて読んでいます。この no を受けて何かを変えた記録はありません。
同じ夜の 23:06〜23:32 に /<スキル名> で呼んだ5回は、セッション記録の上で <command-name>/<スキル名></command-name> という形になっていました。5回とも、最初のツール呼び出しより前に、Base directory for this skill: で始まり SKILL.md の本文(このスキルにしか無い見出し)を含む記録が入っていて、本文がモデルの入力に入っていたことを確かめました。フォールバックになった156回には、この記録は1件もありません。ただし、この5回の起動引数は記録に無く、--restricted の有無は確かめられません(Bash を使っているので、本番と同じ --tools Read,Grep,Glob の構成ではない)。言えるのは、構成の違う呼び出しでは展開されていた、までです。
以前の記事の「拒否されたら別のツールで試してよい」という案内と同じ型で、塞がった経路をモデルが別の経路で補い、補えた回は成功に見えていました。
何を変えたか
スキル名で呼ぶのをやめ、SKILL.md の本文(frontmatter を除いたもの)の $ARGUMENTS を入力フォルダの絶対パスに置き換えて、それをプロンプトとして渡すようにしました(10月2日)。--restricted は、それによる制限を保つために残しました。外した構成での実効的な制限は比べていません。
import re
from pathlib import Path
def skill_prompt(skill_md: Path, arguments: str) -> str:
"""SKILL.md の本文(frontmatter を除く)の $ARGUMENTS を arguments に置き換えたもの。
SKILL.md が無ければ FileNotFoundError、$ARGUMENTS が無ければ ValueError(引数なしで黙って動かさない)。"""
text = skill_md.read_text(encoding="utf-8")
m = re.match(r"---\n.*?\n---\n", text, re.S) # 先頭に BOM があると frontmatter と判定されない
body = text[m.end():] if m else text
if "$ARGUMENTS" not in body:
raise ValueError(f"{skill_md} に $ARGUMENTS が無い(引数の渡し先が分からない)")
head = (f"以下はスキル `{skill_md}` の本文です。"
"本文中のリンクはそのファイルからの相対パスです。\n\n")
return head + body.replace("$ARGUMENTS", arguments)
呼び出し側は -p の値をこの戻り値に替えただけで、SKILL.md や $ARGUMENTS が無いときは claude -p を起動しません。
テストでは「プロンプトが / で始まらない」「$ARGUMENTS が残っていない」「frontmatter の行を含まない」を固定しました。直した形をノートPCで1回走らせ、フォールバックの記録が0件で、最初の呼び出しが入力フォルダの meta.json を読むことだったのを確かめてから、常駐 Mac に入れています。ノートPCに残っている直した後の21回(10月2日・5日)には、フォールバックの記録も、SKILL.md を読んだりスキル名で検索したりした呼び出しもありませんでした(追加の探索を禁じる実装ではありません)。
呼び出しはどれだけ減ったか
運用メモには「探索の手間が消えて費用も約半分」と書いていました。セッション記録で比べ直すと、比べられたのは選ぶ段だけでした。同じモデルの回に絞った中央値です。
| 選ぶ段 | 直す前(2.1.285・67回) | 直した後(2.1.289・8回) |
|---|---|---|
| ツール呼び出し | 10回 | 5回 |
| モデルの応答の数 | 7回 | 3.5回 |
| 入力トークンの累積(キャッシュの読み書きを含む) | 約32万 | 約20万 |
| 出力トークンの累積 | 約3,600 | 約2,700 |
数え方: セッション記録は1つの応答を内容のブロックごとに複数の行に分けて書き、同じ usage を各行に入れているので、応答(メッセージ ID)ごとに1回だけ数えました。入力は input_tokens・cache_read_input_tokens・cache_creation_input_tokens の和で、セッションの中のすべての応答について足した累積です(最初に渡したプロンプトの長さではありません)。
版も入力も違い、直した後は8回しかないので、差がすべて「探す手間」の分だとは言えません。下書きする段と照合する段は扱った題材や長さが違い、比較になりませんでした(下書きする段は、直した後のほうがむしろ多かった)。運用メモの「費用も約半分」は、今回の集計では確かめられませんでした。選ぶ段で半分だったのは、ツール呼び出しとモデルの応答の数の中央値です(入力トークンの累積は約6割。請求額は比べていません)。
自分の環境で確かめるなら
既にある記録から数える(何も走らせない)
claude -p "/<名前> …" の形で呼んでいるジョブがあるなら、セッション記録にこの型の記録が無いかを数えます。スクリプトは記録を読むだけで、出すのは日付・版・入口・コマンド名・件数だけです。
#!/usr/bin/env python3
"""Claude Code のセッション記録から「スラッシュコマンドが見つからず、フォールバックで渡された回」を数える。
出すのは 日付(UTC)・版・入口・コマンド名・件数 だけ。会話の本文は出さない。
使い方: python3 find_fallback.py [~/.claude/projects]"""
import collections
import glob
import json
import os
import sys
root = os.path.expanduser(sys.argv[1] if len(sys.argv) > 1 else "~/.claude/projects")
hits = collections.Counter()
mentions = 0 # 文字列は含むが、型の記録は無いファイル(この件を調べた会話など)
for path in glob.glob(os.path.join(root, "*", "*.jsonl")):
has_mention = has_typed = False
try:
with open(path, encoding="utf-8", errors="replace") as fh:
for line in fh:
if "unknown_command_fallback" not in line:
continue
has_mention = True
try:
rec = json.loads(line)
except ValueError:
continue
att = rec.get("attachment") if isinstance(rec, dict) else None
if isinstance(att, dict) and att.get("type") == "unknown_command_fallback":
key = (str(rec.get("timestamp", ""))[:10], str(rec.get("version")),
str(rec.get("entrypoint")), "/" + str(att.get("commandName")))
hits[key] += 1
has_typed = True
except OSError:
continue
if has_mention and not has_typed:
mentions += 1
for key, n in sorted(hits.items()):
print(*key, n, sep="\t")
print(f"型で数えた件数 {sum(hits.values())} / 文字列だけ含むファイル {mentions}", file=sys.stderr)
10月25日にノートPCで走らせた結果です(Python 3.14.6。スキル名は伏せました。日付は UTC なので、9月26日の3件は日本時間では9月26日 23:56〜27日 00:05 です)。
型で数えた件数 156 / 文字列だけ含むファイル 4
2026-09-26 2.1.283 sdk-cli /<スキル名> 3
2026-09-28 2.1.283 sdk-cli /<スキル名> 14
2026-09-30 2.1.285 sdk-cli /<スキル名> 139
文字列の grep だけだと、この件を調べた会話の記録まで当たります(上の「文字列だけ含むファイル」)。0件は「無い」の証拠になりません(読めないファイルは飛ばし、--no-session-persistence を付けた呼び出しは記録が残らない)。記録の形式は Claude Code の内部のもので、版で変わりえます。
最小の例で比べる
スキルを1つ置いたフォルダで、--restricted の有無を変えて比べる手順です。この記事を書く作業ではこれを走らせていません。2.1.310 でどうなるかは、走らせて確かめてください。各実行に --session-id で ID を付け、その回のセッション記録だけを次のスクリプトで調べます。
#!/usr/bin/env python3
"""1つのセッション記録で、スキルの本文が入力に入ったか・フォールバックになったかを数える。
使い方: python3 check_session.py <session-id> <SKILL.md の本文にしか無い文字列>"""
import glob
import json
import os
import sys
sid, marker = sys.argv[1], sys.argv[2]
files = glob.glob(os.path.join(os.path.expanduser("~/.claude/projects"), "*", sid + ".jsonl"))
if len(files) != 1:
sys.exit(f"セッション記録が {len(files)} 件(1件のはず): {sid}")
fallback = body = 0
with open(files[0], encoding="utf-8", errors="replace") as fh:
for line in fh:
try:
rec = json.loads(line)
except ValueError:
continue
if not isinstance(rec, dict):
continue
att = rec.get("attachment")
if isinstance(att, dict) and att.get("type") == "unknown_command_fallback":
fallback += 1
if rec.get("type") == "user" and rec.get("isMeta"): # ツールの結果(Read した中身)は数えない
c = rec.get("message", {}).get("content")
text = c if isinstance(c, str) else json.dumps(c, ensure_ascii=False)
if "Base directory for this skill:" in text and marker in text:
body += 1
print(f"fallback={fallback} skill_body={body}")
mkdir -p /tmp/skill-probe/.claude/skills/echo-probe && cd /tmp/skill-probe
cat > .claude/skills/echo-probe/SKILL.md <<'EOF'
---
name: echo-probe
description: 確認用。決まった1行だけを返す
---
次の1行だけを返してください: SKILL-BODY-LOADED $ARGUMENTS
EOF
opts=(--output-format json --tools Read,Grep,Glob --allowed-tools Read,Grep,Glob
--strict-mcp-config --permission-mode dontAsk)
A=$(uuidgen | tr A-Z a-z); B=$(uuidgen | tr A-Z a-z)
claude -p "/echo-probe abc" --session-id "$A" "${opts[@]}" > a.json
claude -p --restricted "/echo-probe abc" --session-id "$B" "${opts[@]}" > b.json
python3 ~/check_session.py "$A" SKILL-BODY-LOADED # check_session.py は ~ に保存しておく
python3 ~/check_session.py "$B" SKILL-BODY-LOADED
私の手元の記録に当てると、9月26日 23:06 の(展開された)回は fallback=0 skill_body=1、フォールバックの回は fallback=1 skill_body=0 でした(目印は、そのスキルの本文にしか無い見出し)。記録が見つからなければ止まります。fallback=0 だけでは展開の証拠にならないので、skill_body=1 まで見ます。a.json と b.json の result は同じになりうることにも注意してください(フォールバックでも、モデルが SKILL.md を見つければ同じ1行を返す)。
守らない範囲
- frontmatter に書いた設定。この実装は frontmatter を適用せず、ツール構成を CLI の引数で明示している(管理設定などの制約は別に受ける)。
$ARGUMENTS以外の置き換えや前処理もしない - 先頭に BOM のある SKILL.md(frontmatter と判定されず、frontmatter ごと渡る。10月25日に確認)
- 将来の版で、スキルの読み込みの挙動が変わった場合の影響(未検証)
まとめ
記録した構成(--restricted ほか)の claude -p では、対象のスキルがスラッシュコマンドとして解決されていませんでした。Claude Code はそれを失敗にせず、「手持ちのツールでやれ」とモデルに渡し、モデルはたいてい手順書を探し当てました。だから、私が見ていた成果物と照合の結果からは、1週間気づきませんでした。モデルに「スキル一覧にあるか」と聞いた答えも、補助的な手がかりにしかなりません。
確かめられたのは、セッション記録に残る型の記録(フォールバック)と、本文が入力に入った記録でした。スキルの本文を自分で渡すようにしてからは、手順の取得が、モデルが SKILL.md を探し当てることに依存しなくなりました。
※ この記事は Zenn に投稿した同名記事(https://zenn.dev/masamitsu_sera/articles/7363154f42de02 )の転載です。