Claude Codeで自作スキル・サブエージェントを作ったが既存セッションから呼べなかった件
Claude Code(Claude DesktopのLocal Agent Mode)で自作スキルとサブエージェントを~/.claude/配下に置いた。そのあと既に動いていた別セッションのClaudeに頼んだら「そんなスキルは知らない」と返ってきた。原因と確認方法を残しておく。
何を作ったか
ユーザーレベルに以下2つを置いた。
~/.claude/skills/blog-md-reviewer/SKILL.md(ブログ校正用スキル)~/.claude/agents/blog-reviewer.md(校正用サブエージェント)
起きたこと
別セッションのClaudeに「この記事を校正して」と頼んだら、blog-md-reviewerもblog-reviewerも認識されていなかった。代わりに、目視と記憶ベースで校正された結果が返ってきた。
原因
スキルとサブエージェントで反映の仕組みが違う、というのが本質だった。
スキルはライブ検出される(条件付き)
Claude Codeは~/.claude/skills/を含むスキルディレクトリをファイル変更監視している。配下のスキルを追加・編集・削除すると、セッションを再起動しなくてもそのセッションに反映される。
ただし例外がある。セッション開始時に存在していなかったトップレベルのスキルディレクトリは監視対象にできないため、新規にそのディレクトリを作った場合だけ再起動が必要なのだそう。
今回のケースは、~/.claude/skills/自体をこのとき初めて作成した。別セッションの起動時点ではこのディレクトリが存在しなかったため、その後配下に置いたスキルもライブ検出されなかった。
サブエージェントはセッション開始時ロードのみ
サブエージェントの方はそもそもライブ検出がない。ファイルを直接置いた場合は必ずセッション再起動が必要。/agentsコマンドで対話的に作った場合のみ即時反映される。
確認方法
新規セッションで以下を聞くと、スキャン結果がわかる。
- 「使えるスキル一覧を出して」
- 「使えるサブエージェント(
Agentツールのsubagent_type)を一覧で出して」
リストに自作のものが含まれていれば認識されている。なければファイルの場所か形式の問題なので、
~/.claude/skills/<name>/SKILL.mdの位置~/.claude/agents/<name>.mdの位置- フロントマターの
descriptionの有無
を確認する。
まとめ
今回のように~/.claude/skills/自体を新規作成したパターンでは、Claude Codeを開き直す。再起動後は、スキルがトリガーフレーズで自動発動し、サブエージェントはAgentツールからsubagent_type: "blog-reviewer"で呼び出せるようになる。
なお、~/.claude/skills/がすでに存在する状態で配下にスキルを追加した場合は、再起動なしで反映される。サブエージェントを足した場合は、ファイル直置きならセッション再起動、/agentsコマンドからの作成なら即時反映と切り替わる。
残った疑問
- プロジェクトレベル(
<project>/.claude/skills/、<project>/.claude/agents/)に置いた場合の挙動も別途確認が必要
参考リンク: