Claude Code Skills が発火しない3ケース — ローカル・クラウド・stale前提の設計ギャップ

Posted at 2026-09-04

この記事で解決できること

Skills を整備したのに動かない、という状況の原因を3ケースに分けて解説します。

環境

Claude Code on the Web（CCR） + ローカルセッション混在
~/.claude/skills/ による Skills 管理
コンテンツ自動化パイプライン（content-executor）

結論

Skills が発火しない原因は以下の3つのいずれか（または複合）:

実行環境の境界: CCR（クラウドルーチン）はローカルの ~/.claude/skills/ を読まない
設定ソースの誤認: ローカルの SKILL.md を修正しても Authoritative がクラウド設定にある場合は反映されない
前提の陳腐化: コンセプト・設計変更後、Skills の前提が古いままになっている

ケース1: クラウドルーチンがローカル Skills を読まなかった

記事投稿で Qiita 403（frontmatter 形式違反）と Zenn title 70 文字超過が連発したため、2026年6月23日に Skills を整備した。

~/.claude/skills/article-gate/SKILL.md  # 共通チェック6項目
~/.claude/skills/qiita/SKILL.md          # Qiita 固有ルール
~/.claude/skills/zenn/SKILL.md           # Zenn 固有ルール

ローカルの手動セッションでは正常に invoke された。しかしクラウドルーチン（CCR）での content-executor が同じ作業をしてもSkillsは一切呼ばれていなかった。

原因

~/.claude/skills/ はローカルファイルシステム上にある。CCR のサンドボックス環境からはアクセス不可能。

対策

クラウドルーチンが Read できるプロジェクトファイル（docs/adapt-spec-*.md）に仕様を移植する。

実行環境	Skills の扱い
ローカル手動セッション	`~/.claude/skills/` が有効
CCR（クラウドルーチン）	プロジェクトファイル（`docs/`等）を Read する設計が必要

ケース2: SKILL.md を修正したのに反映されなかった

2026年6月19日、Qiita/Zenn の adapted 記事 frontmatter に問題があり、ローカルの ~/Documents/Claude/Scheduled/ にある SKILL.md を修正した。しかし自動化の挙動が変わらなかった。

原因

稼働中の自動化（content-executor）が参照していたのは /schedule のクラウド設定側のプロンプト。ローカルのSKILL.mdは読まれていなかった。

「ローカルファイルが Authoritative」という誤認が原因。

対策: Authoritative を確認してから修正する

/schedule list で稼働中ルーチンのプロンプトを確認
そのプロンプトが参照しているファイルを特定
そのファイルを修正する

ケース3: コンセプト変更後も古い前提の Skills が動き続けた

2026年6月7日に masatoman.net の主軸を切り替えた（工務店特化 → AI業務設計実験ログ）。しかし稼働中のクラウドルーチン3本と Skills の前提は旧コンセプトのままだった。

6月17日の棚卸しまで、1ヶ月以上古い前提で処理が続いた。

原因

Skills は一度整備すると、前提が変わっても自動で更新されない。コンセプト変更を Skills に伝播させる仕組みを入れていなかった。

対策: コンセプト変更時の棚卸しチェックリスト

~/.claude/skills/ 以下のSKILL.mdを全件確認、古い前提が残っていないか
クラウドルーチンのプロンプトに旧コンセプトのキーワードが残っていないか
adapt-specファイルの仕様が現在の設計と一致しているか

まとめ

ケース	問題の層	対策
ケース1	実行環境の境界	クラウドはプロジェクトファイル参照、ローカルは ~/.claude/skills/
ケース2	Authoritative の誤認	/schedule list でソースを確認してから修正
ケース3	前提の陳腐化	コンセプト変更時に Skills 棚卸しをチェックリストに追加

Skills は「書いたから動く」ではなく「実行環境・設定ソース・前提の3軸が揃ったときだけ動く」。設計に組み込む必要がある。

AI ツールを業務に組み込む設計の実験ログを書いています。 https://masatoman.net

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up