0. はじめに：なぜ「Skillsそのもの」を議論するのか

本記事では、Codex Skillsを勉強会で実際に使ってみた体験をもとに、
エンジニアと非エンジニアの間でどのような認識のズレが生まれたのかを整理しました。
あわせて、Skillsを「チームで仕事のやり方を共有する仕組み」として使うために、
どのような前提や設計が必要なのかを考察しています。

Skills は、AI エージェントに対して
「仕事のやり方」をまとめて教えるための仕組み です。

一方で、実際に勉強会などで触れてみると、

• Prompt と何が違うのか分からない
• いつ Skills を作るべきか判断できない
• 「Skill を設計する」と言われても、設計対象が見えない

といった声も多く聞かれました。

本記事では、社内勉強会（第10回「AIハッカソン・黙々勉強会」）を通じて見えてきた
「エンジニアが考える Skills の捉え方」 と
「初心者（非エンジニア）が実際に感じたギャップ・課題」 を並べて整理し、
今回はCodex Skillsを通じて、
Skillsをどう理解し、どう設計・運用を考えていくか の課題感を整理しています。

単なる機能紹介ではなく、
Skills を“設計対象”としてどう扱うか に焦点を当てます。

対象読者

• Skillsを普及させたいがうまくいかないと悩んでいる方
• Skillsを使いこなしたいと思っている初学者の方

記事の位置付け

本記事は、Skillsの「正しい使い方」を定義するものではありません。
実際に触れてみた結果として、何がうまく言語化でき、何がまだ曖昧なままなのかを整理した、現時点での所感・見解をまとめたものです。
ただし、この捉え方が最適かどうかはまだ検証途中であり、今後変わる可能性がある点には注意が必要です。

この記事で扱うこと／扱わないこと

• 扱うこと
  • Skillsを実際に使ってみて感じた違和感
  • 技術者と初心者の認識のズレ
  • 今後考えるべき論点
• 扱わないこと
  • Skillsの完全な定義
  • 正しい設計パターン集
  • 実装チュートリアル

1. Codex Skills とは

Codex Skills は、AI エージェントに対して
特定のタスクや判断を安定して実行するための知識・手順・制約をまとめて定義する仕組み です。
例えるなら、コードでいう関数やクラス、あるいは業務手順書をAI向けに設計したものに近いイメージです。

Skillsが生まれた背景や考え方の詳細については、外部記事でもよく触れられていますので本記事では割愛します。

• 参考（Codex Skillsについての概要）：
  https://zenn.dev/naokky/articles/202601-codex-skills

本記事では特に、次の点を前提とします。

• Skills は「単発の指示」ではなく 再利用される設計単位
• Prompt や Tool とは異なり、仕事の進め方そのものを切り出す
• 人間が読んで理解できることを前提としたドキュメント（判断や手順を含む）として管理される

この前提を踏まえ、以降では Skills をどう捉えると理解しやすいかを掘り下げます。

2. Skillsに対して見えてきた違和感

技術者側では自然に受け入れられていた前提が、
初心者にとっては共有されていなかった、という場面が多く見られました。

2.1 技術者視点：Codex Skills をどう捉えているか

技術者視点では、Codex Skills を
「仕事のやり方を切り出した設計単位」 として捉えています。

Skills は Prompt の延長ではない

• Prompt：その場限りの指示
• Tool：実行手段
• Skill：どう考え、どう進め、どこまでをOKとするという判断・手順・制約

Skills は「何をするか」よりも、
「どういう前提で判断し、どう進めるか」 を固定化するためのものです。

なぜ Skills が必要なのか

実際の運用では、以下の課題がありました。

• Prompt が肥大化し、意図が読み取りづらくなる
• 同じタスクでも毎回書き直す必要がある
• 指示の背景が属人化しやすい

例えば「〇〇対応のたびに Prompt を書き直していた」「レビュー観点が人によってズレた」なんてことがこれまではあったのではないでしょうか。

Skills に切り出すことで、

• 再現性を高められる
• 設計意図を共有しやすくなる
• AI エージェントとの役割分担が明確になる

といった効果が期待できます。

2.2 初心者から見た Codex Skills（体験とギャップ）

本勉強会では Codex Skillsについての概要 の記事を参照して取り組みました。

勉強会で Codex Skills に初めて触れたとき、
正直な第一印象は「何が有用なのか分からない」「Promptと何が違うの？」でした。

まず、プロンプトで議事録の作成をお願いした時と、Skillsを作成した時と、出力がほとんど変わりません。
また、Skillsを参照してほしいのに、何度依頼しても、

＜今回参照したSkillsはありません＞

との出力！

＜Skillを参照して＞＜参照したSkill名のログを出して＞

と、手を変え品を変え、出してもらおうとするのに、同じ回答が繰り返されました。

Skill作成時のお作法についても理解が足りておらず、
スキルを配置するディレクトリや書き方のフォーマットを有識者にもチェックしてもらい、
修正することでようやく参照してもらえました。

参照の成否以前に、“何をSkillsとして切り出すと嬉しいのか”が掴めず、
価値を体感できなかったため、

• Prompt に書いていた内容を別ファイルに分けただけでは？
• どのタイミングで Skill を作る判断になるのか分からない
• 「設計する」と言われても、設計対象が抽象的に感じた
  などの疑問が残りました。

他の参加者は参照してもらえていたものの、Skillとして切り出す価値やゴール像が見えていない状態では、試行錯誤が学びにつながりにくいと感じました。

※ 参考：初学者がSkillsを試した際の画面例
（Skillを指定しているつもりでも、参照状況が分からず戸惑ったケース）

2.3 なぜ Skills の理解にズレが生まれたのか

技術者と初心者の認識を並べてみると、次のような違いがありました。

技術者側の前提

• Skills は設計単位
• 再現性・責務分離のための仕組み
• 「あとから読む人（AI含む）」を意識する

初心者側の受け取り

• Prompt の延長
• 便利なテンプレート
• 書き方のルールがよく分からないもの

このズレの原因は、
Skills が 実装の話ではなく、設計思想の話 である点にあると考えています。
そのため、正解例が見えにくく、初学者ほど手が止まりやすいものになります。

コードや Prompt は「書けば動く」一方で、
Skills は 「どう切り出すか」を考えないと形にならない ため、
初学者にとっては難易度が高く感じられました。

2.4 Skills を「Skills」たらしめる要素は何か

議論を通じて、
「これは Skills と呼んでもよさそうだ」と感じた観点がいくつかありました。

現時点では次のような要素が関係していそうだと考えています。

• 目的と責務が明確か
• 他の文脈から切り離して再利用できるか
• 人間が読んで意図を理解できるか
• 判断・手順・制約を固定化するための工夫があるか

これらを満たしていない場合、
それは単なる Prompt の断片であり、
まだ Skills とは呼びづらい のではないかと感じています。

これらはまだ仮説段階であり、
今後の実践や失敗を通じて見直される前提です。

3. 勉強会を通じて見えた今後検討すべき論点

今回の勉強会を通じて、
「これは今後ちゃんと考えないといけない」と感じた論点がいくつか浮かび上がりました。

• Skillを作る・採用する判断基準はどこに置くべきか
• Skillと他の技術（Prompt、Templateやサブエージェントなど）との使い分けはどう考えるか
• 初心者が詰まったときの“逃げ道”をどう用意するか
• Skillの管理・棚卸しをどう回すか

これらに対する明確な答えは、現時点ではまだありません。
これらの論点は、今後の勉強会や実践を通じて、
少しずつ言語化・更新していく必要があると感じています。

4. まとめ：Skillsは「チームで使われてはじめて意味を持つ設計対象」

今回の勉強会を通じて強く感じたのは、Skillsを実運用に乗せる上で重要な前提です。
Skills は「一部の技術者がうまく使えればよい仕組み」ではありません。
非エンジニアが Skills の意図を理解し、使える状態になってはじめて、
仕事の進め方や判断基準をチーム全体で共有する仕組みとして機能すると感じました。

なお、Skills を純粋に技術者向けの自動化手段として使うのであれば、
非エンジニアが使えなくても問題にならないケースもあります。
本記事では、Skills を「仕事のやり方や判断基準をチームで共有する仕組み」として捉えた場合に、
なぜ初学者が使えない状態が課題になるのかを扱っています。

その上で、Codex Skills を議論して改めて感じたのは、
Skills はコードと同じく「設計対象」である ということです。

一方で現時点での結論をあえて一言でまとめるなら、
Skillsは便利な仕組みである一方、
設計思想を共有しないと一気に扱いづらくなる仕組み だと感じています。

だからこそ、
「どう使うか」よりも先に、
「どう捉えるか」を継続的に言語化していく必要がありそうです。

便利だから使うのではなく、

• どう切り出すか
• どう共有するか
• どう育てるか

を考える必要があります。

技術者の視点だけでなく、初心者が感じた違和感やつまずきは、
Skills をより良く使っていくための重要なヒントでした。

Skillsをどう作るか迷っている方は、まず普段利用している Prompt を1つ題材にして、

• 「これはSkillとして切り出す意味があるのか？」
• 「そのPromptは“毎回ほぼ同じ判断・手順・品質基準”を含んでいるか？ 含むならSkill候補」

を考えてみるところから始めるのも一案だと思います。

本記事は執筆にあたり以下の方にもご協力を頂きました。

• 勉強会の開催：第10回AIハッカソン (LinkedInページ)
• 初学者目線：https://zenn.dev/yumiko_cs1007
• 記事の引用：https://zenn.dev/naokky