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

「Skillsを整備したのに、思ったタイミングで呼ばれていない」——Claude Codeで自動化を組んでいると、この状況に何度か出会う。

この記事は、masatoman.netのコンテンツ自動化（content-executor）と記事投稿パイプラインを運用する中で2026年6月に連続して踏んだ、Skillsの非発火パターン3ケースの実験ログです。ケースの構造と、再発を防ぐ設計判断軸を整理します。

結論

Skillsが発火しない原因は1つではない。「どの実行環境で動くか」「誰が真の設定ソースか」「前提が今も有効か」——この3軸を設計に組み込まないと、整備したSkillsは静かに無視される。

「Skillsをもっと丁寧に書けば解決」ではなく、実行環境と設定の構造から設計し直す必要があります。

この記事の前提

• スタック: masatoman.net（Next.js + Supabase）+ Qiita/Zenn/はてな/Dev.to外部配信
• 運用: content-executorというクラウドルーチン（CCR）で記事を自動生成→各媒体にadapted→push
• Skills構成: article-gate（共通6項目）+ qiita/zenn/note/masatoman-publish（媒体別）の2層設計
• 発見時期: 2026年6月、Qiita 403事故・Zenn 70文字オーバー事故の再発防止構造化の過程で判明

「Skills整備の成功談」ではなく、「なぜ整備したのに動かなかったかを構造から理解した設計変更の記録」です。

読者のよくある詰まり（「それ俺だ」を作る）

こういう状況になりやすい。

1. Skills を整備してローカルでは動いた: ~/.claude/skills/article-gate/SKILL.md を書いて、ローカルでの手動セッションではinvokeされる
2. クラウドルーチンでは呼ばれない: CCRで動くcontent-executorが同じ作業をしても、Skillは無視される
3. Skills を編集したのに効かない: ローカルのSKILL.mdを正しく修正したつもりが、稼働中の自動化の挙動が変わらない
4. 前提が変わったのにSkillsが古いまま動く: コンセプトを変えた後、Skillsには旧前提が残っていて、古い判断軸で処理し続ける

全部、「Skillsがどのレイヤーでどのタイミングで読まれるか」の構造を押さえれば予防できるハマり方です。

---

実際に起きたこと（3ケース）

ケース1: article-gate Skillを整備したのに、Qiita 403とZenn 70文字オーバーが止まらなかった（2026-06-23）

記事投稿時に媒体ごとのルールを守れていない事故が続いた。Qiita 403（frontmatter形式違反）とZenn titleの70文字超過が連発していた。

対策として article-gate（共通6チェック項目）を作り、その下にqiita/zenn/note/masatoman-publishの媒体別Skillを追加した。ローカルで手動セッションを動かすと、Skillがinvokeされてチェックが走る。

しかし問題はそこではなかった。 content-executor（クラウドルーチン）が記事を生成・adapted・pushするフローの中で、これらのSkillsは一度も呼ばれていなかった。

結果: 2層Skill構造は整備したが、クラウドルーチン側は adapt-spec ファイル（masatoman.net/docs/adapt-spec-{媒体}.md）をReadする設計に切り替えることで解決。Skillはローカル手動セッション専用、クラウドルーチンはプロジェクトファイル参照、という役割分担になった。

→ ケース1の構造: 実行環境ごとにSkillsのアクセス可否が異なる

ケース2: ローカルのSKILL.mdを修正したのに稼働中の自動化に反映されなかった（2026-06-19）

QiitaとZennのadapted記事frontmatterに問題があり、生成側を直そうとした。ローカルに ~/Documents/Claude/Scheduled/ という古いSKILL.mdがあり、そこが正しいテンプレートを持っていたので編集した。

しかし反映されなかった。 実際に適用されていたのは /schedule のクラウド設定側のプロンプトで、ローカルのSKILL.mdは参照されていなかった。「ローカルSKILL.mdが真の設定ソース」という誤認だった。

「直した場所」と「実際に動いている場所」が別だった。

→ ケース2の構造: Authoritative（真の設定ソース）を誤認すると、修正が永遠に効かない

ケース3: コンセプトピボット後も古い前提のSkillsが動き続けた（2026-06-17）

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

6月17日の棚卸しで発覚するまで、1ヶ月以上、古い前提のまま処理が続いていた。ローカルの ~/Documents/Claude/Scheduled/ に置いてあるSKILL.md群はクラウド設定と不一致の状態で放置されていた。

→ ケース3の構造: SkillsはRead-only、前提の陳腐化を自分で検知しない

---

原因分析

3ケースを並べると、共通する構造が見えてくる。

ケース	原因の層	誤認していたこと
ケース1	実行環境の境界	ローカルで動けばクラウドでも動くと思っていた
ケース2	設定ソースの所在	ローカルファイルが真のソースだと思っていた
ケース3	前提の鮮度	Skillsは一度整備すれば維持されると思っていた

Skillsは「書いたから動く」ではなく「実行環境・設定ソース・前提の3軸が揃ったときだけ動く」。

判断軸（読者が当てはめられる形）

軸1: 実行環境の境界を先に決める

新しいSkillsを書く前に、「このSkillはどの実行環境で使うか」を決める。

• ローカル手動セッション: ~/.claude/skills/ に置けば機能する
• CCR（クラウドルーチン）: ローカルのSkillsファイルは読めない。ルーチンが Read できるプロジェクトファイル（docs/adapt-spec-*.md 等）に仕様を書く
• 両方: 別のファイルに別の形式で書く必要がある。「1ファイルで両対応」は現状できない

詳細な cloud/local の境界については

で解説している。

軸2: Authoritative（真の設定ソース）を確認してから修正する

「自動化の挙動がおかしい」と思ったとき、修正の前に「実際にどのファイルが参照されているか」を確認する手順:

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

ローカルSKILL.mdを修正しても稼働中クラウドルーチンに反映されない理由は、Authoritativeがクラウド設定側にあるため。

軸3: コンセプト変更時はSkillsを棚卸しのトリガーに入れる

主軸・ターゲット・フローを変えたとき、Skillsの前提は自動で更新されない。変更発生時のチェックリストにSkillsの棚卸しを入れておく:

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

今日やること（3つ以内）

1. 自分のSkillsの実行環境を確認する: 各Skillが「ローカル用」か「クラウドルーチン用」かをREADMEに1行書く。両方対応のつもりで片方しか効いていないケースが多い
2. 稼働中の自動化のAuthoritativeを特定する: /schedule list（CCRの場合）で実際に動いているプロンプト・ファイルを確認し、修正先を把握する
3. 前回コンセプトや設計を変えたのがいつか確認する: その後Skillsの棚卸しをしていなければ、今やる

---