create-skill

create-skill

新しい Agent Skill を、efoo-team の二層スキル管理の仕組みに沿って対話的に作成するスキル。

目的

ユーザーが「何を実現したいか」を質問で見極めた上で、本質的に高品質な（正しく発火し、正しく動く）Agent Skill を作成する。SKILL.md の執筆だけでなく、スキル化の要否判定・配置決定・検証までを1つのワークフローとして完遂する。

追加指示の扱い

ユーザーが引数として渡した要望・追加指示（Claude では /create-skill の引数、Codex では $create-skill の引数）は、本スキル内の他の方針より優先して適用する。ただし「ヒアリングを省略しない」「検証未実施のまま完成としない」などの重要な制約に反する場合は、実行せず直ちに停止して確認を求める。引数には、作りたいスキルの概要、対象プロジェクト、参考にしたい既存スキルなどが含まれる可能性が高い。引数が空の場合は、会話の文脈から要望を把握して標準フローを実行する。

基本方針

• 意図が先、スキルが後: ユーザーが何を実現したいかを確認できるまで SKILL.md を書き始めない。スキルは手段であり、hook / CLAUDE.md / 単体スクリプト / サブエージェントが適切な場合はそちらを提案する
• 知識の正本を複製しない: スキル執筆の一般原則（progressive disclosure 3階層・description 執筆・自由度判断・eval 先行）の正本は agent-native-project-design/references/skill-authoring.md である。本スキルはその原則を適用する対話ワークフローを提供するのであって、原則の写しを持たない
• 迷ったらプロジェクト層: 共通層に置くのは複数プロジェクトでの必要性が実証されたときだけ
• 具体例で書く: 想像上の要件でスキルを書かない。ユーザーから実例（実際の入力と期待する出力）を引き出してから書く
• 検証なくして完成なし: SKILL.md を書いただけでは完成ではない。検証（check-skills.py PASS・発火テスト）まで、共通層の場合はさらに README.md の表更新までが「作成」である

前提知識のロード

Phase 1 に入る前に、以下を読む。

1. skill-authoring.md（執筆原則の正本） — 次の順でパス解決する:
   • ~/ghq/github.com/efoo-team/skills/skills/agent-native-project-design/references/skill-authoring.md（リポジトリ checkout）
   • 無ければ ~/.agents/skills/agent-native-project-design/references/skill-authoring.md（インストール済み実体）
2. references/registration.md（本スキル同梱） — 配置先別の登録手順・YAML クォート規則・検証コマンド。Phase 3 以降で使う
3. authoring-insights.md（外部知見の補遺。正本は agent-native-project-design 側） — skill-authoring.md と同じ順でパス解決する:
   • ~/ghq/github.com/efoo-team/skills/skills/agent-native-project-design/references/authoring-insights.md（リポジトリ checkout）
   • 無ければ ~/.agents/skills/agent-native-project-design/references/authoring-insights.md（インストール済み実体） スキル4類型・description の追加注意・ガイダンス形式・トリガー評価・外部スキル監査を収める。Phase 2 / 4 / 6 で使う
4. agent-prompt-design（文面の執筆原則） — skill-authoring.md と同じ順でパス解決する:
   • ~/ghq/github.com/efoo-team/skills/skills/agent-prompt-design/SKILL.md（リポジトリ checkout）
   • 無ければ ~/.agents/skills/agent-prompt-design/SKILL.md（インストール済み実体） 記述高度・既習概念の指名・工程分離・停止条件など、SKILL.md 本文の文面を書くときの一般原則。Phase 4 の執筆で適用する

パス解決が checkout 優先なのは意図的である（本スキルは checkout 上で編集する作成時ツールであり、authoring 中の最新の原則を読むため）。実行時ツール（pr / agents-md-sync 等）の installed（~/.agents/skills）優先とは逆になる。

実行手順

Phase 1: 意図の明確化（ヒアリング）

まず調査、次に質問。 引数と会話から要望を把握したら、質問の前に読み取り専用で調査する:

• 共通層の一覧（このリポジトリ skills/ 配下と README.md の表）・インストール済み ~/.agents/skills/（common + external の実配布物）・AGENTS.md「統合しない判断の記録」節を読み、類似スキルを洗い出す
• 対象プロジェクトが特定できる場合、そのリポジトリの既存スキル（.agents/skills/・.claude/skills/）と CLAUDE.md / AGENTS.md を確認する

その上で、利用可能な質問機能を用いて質問する。一度に最大4問まで、平易な言葉で、回答例つき（推奨には（推奨）と明記）で行う。うち利用範囲は省略不可の必須質問とする: 引数や会話の文脈から自明に見えても省略せず、「このプロジェクトのみで使う（推奨）/ 複数のプロジェクト・チーム全体で使う」の選択肢付きで必ず質問する。この回答を Phase 3 の層（プロジェクト層 / 共通層）の判断材料にする。

カテゴリ	確認すること
課題	どんな作業・判断を繰り返しているか。現状どこで失敗・手戻りが起きているか
成功の姿	スキル完成後、何がどう変わるか。良い出力の具体例
発火場面	どういう時に使われてほしいか。そのときユーザーが実際に言いそうな言葉（description に埋め込むトリガー語彙の採取）
利用範囲（必須質問）	誰が・どのプロジェクトで・どのツール（Claude Code / Codex / opencode）で使うか。上記のとおり選択肢付きで必ず質問し、層の判断材料にする
自由度	毎回ほぼ同じ手順か（低自由度＝スクリプト化候補）、状況判断が必要か（高自由度＝指針で書く）
出力	期待する出力形式（ファイル・レポート・コード等）。その出力は客観的に検証可能か（Phase 6 の eval 設計が定量になるか定性になるかを決める）

具体例を最低1つ引き出す: 「最近この作業を実際にやった例」を挙げてもらい、入力・途中の判断・期待する出力を具体化する。実例が出ないうちは要件が固まっていないと判断する。

Gate: 課題・発火場面・利用範囲が確認できるまで Phase 2 に進まない。

阶段 2：判断是否需要创建技能以及是否存在重复

1. 判断机制是否适用。技能是一种按需触发的机制；在未触发的会话中，它等同于不存在。遇到以下情况时，建议使用技能以外的机制：
   • 必须始终遵守的保证（must always / never 级别）→ hook
   • 所有会话都始终需要的章程或规范 → CLAUDE.md / AGENTS.md
   • 输入输出完全确定的处理 → 独立脚本（必要时让技能只充当调用脚本的薄封装）
   • 主要目的是隔离大量上下文或并行处理 → 子 Agent
   • 仅在特定场景下才需要的步骤、知识或判断标准 → 技能（继续）
2. 判断类型。确定技能属于 4 种类型（reference / technique / pattern / discipline-enforcing）中的哪一种（authoring-insights.md §1）。类型会影响阶段 4 的写法和阶段 6 的测试方法。
3. 判断是否重复。确定它与阶段 1 中发现的类似技能之间的关系：
   • 现有技能已足够 → 不创建，说明如何使用现有技能后结束
   • 修改或扩展现有技能即可满足需求 → 不新建，建议修改现有技能
   • 创建新技能，但仍有类似技能 → 创建，并在 AGENTS.md 的「不整合的判断记录」一节登记不进行整合的理由
4. 向用户说明判断结果及依据，并征得同意。

关卡：在获得「将新建技能」的同意之前，不得进入阶段 3（如果选择了技能以外的机制，则超出本技能的范围，应报告后续处理内容并结束）。

阶段 3：确定放置位置和名称

参考 references/registration.md，确定以下事项，并一并向用户确认。

决定事项	判断标准
层级	犹豫时选择项目层。只有经过验证，确认多个项目都需要时，才选择通用层（efoo-team/skills）
类型	team-owned / external（如果权威来源位于外部仓库，则仅订阅。禁止复制放置 SKILL.md）
分发对象	所有 Agent / 仅限特定 Agent（metadata.internal: true + setup.sh 单独条目）
触发方式	auto（根据 description 自动触发）/ explicit-only（3 项配置：disable-model-invocation: true + agents/openai.yaml + 开头的门控语句。参见 skill-authoring.md §2）。建议多阶段工作流以及涉及 Git 操作等副作用的技能采用 explicit-only
名称	使用 kebab-case，长度为 1〜64 个字符。不得使用 helper / utils 等含义模糊的词。检查本仓库 skills/ 目录和已安装的 ~/.agents/skills/（common + external 的实际分发内容），确保没有冲突或遮蔽（不进行跨项目检查——项目层由各所有者自行负责）

关卡：在就层级、类型、分发对象、触发方式和名称这 5 项达成一致之前，不得进入阶段 4。

阶段 4：设计与编写

1. 按照 skill-authoring.md 的原则进行设计。尤其注意：
   • description：使用第三人称，按 前置优先顺序编写「要做什么 + 何时使用 + 触发词」这 3 个要素（第一句写「要做什么 + 主要触发词」，边界条件放在后半部分）。直接使用阶段 1 中收集到的用户用词。如果存在相邻技能，也要说明「何时不使用，以及那时应该使用哪个技能」的边界。auto 技能建议控制在估计 150 个 token 以内（日语约 250 个字符）（由 check-skills.py 检查。依据和详情参见 skill-authoring.md §2）
   • 如果是 explicit-only：将门控语句「Only use when the user explicitly invokes / (or $ in Codex). Never auto-invoke.」放在 description 的开头，并且除 disable-model-invocation: true 之外，还要在 <skill>/agents/openai.yaml 中附带以下内容（Codex 不识别 disable-model-invocation）：

     policy:
       allow_implicit_invocation: false
     

   • description 的其他注意事项（authoring-insights.md §2〜3）：不要在 description 中写入步骤或阶段数量等工作流摘要（这会导致模型不阅读正文而走捷径）。如果预计 auto 技能的触发能力较弱，可以强调「即使用户没有明确说出◯◯，也要使用」。不要包含 < >。名称不得包含连续连字符；应采用动名词形式或直接说明「要做什么」
   • 结构：不限制 SKILL.md 正文的行数。正文篇幅根据 skill-authoring.md §1「正文篇幅的判断」中的 4 个问题决定（删除后是否会导致错误／模型是否已经知道／是否会在同一次触发中同时需要／不提供是否会悄然降低效果）。只有互斥的内容才拆分到 references/ 中，不要以行数作为拆分理由（超过 100 行时，在开头添加目录，并使用能体现内容的文件名）。即使超过官方 500 行的阈值，也要依据这 4 个问题自主判断，不要向用户解释篇幅合理性或征求指示。引用仅允许从 SKILL.md 向下一级
   • 指导形式：根据要防范的失败类型选择（authoring-insights.md §4）。如果要规范输出形式，应提供肯定式模板，而不是列出禁止形式。规训型技能应附带合理化反驳表和 red flags。与其堆叠全大写的 MUST，不如说明「为什么重要」
   • 脚本：对于自由度较低的处理，将固定脚本放入 scripts/，并在正文中明确说明是要运行脚本，还是将其作为参考阅读
   • 只添加特有上下文：不要写 Claude 已经知道的一般知识或显而易见的训诫。只写项目或团队特有的值、判断标准和易踩的坑
2. 先提供大纲：提供 name / description 提案、正文标题结构和随附文件清单，并征得用户同意。
3. 获得同意后再编写正文。frontmatter 必须包含 name、description、metadata.tags。严格遵守 YAML 引号规则（registration.md §6）。对于包含多阶段工作流的技能，应加入可复制的检查清单，以及「在获得用户回答之前不得继续」的关卡。

关卡：在获得对大纲（步骤 2）的同意之前，不得开始编写正文。

阶段 5：注册

按照 registration.md 中针对不同放置位置的步骤（§2〜§5），更新注册信息和分发设置。至少包括：

• 通用层 team-owned：更新 README.md 中的表格和技能数量
• 仅限特定 Agent：除上述内容外，还需设置 metadata.internal: true + setup.sh 单独条目
• external：添加 setup.sh 条目（不放置 SKILL.md）
• 项目层：权威来源 + .claude/skills symlink（无需在 efoo-team/skills 中操作）

Phase 6: 検証と報告

1. 共通層は python3 ~/ghq/github.com/efoo-team/skills/scripts/check-skills.py を実行し RESULT: PASS を確認する。プロジェクト層は python3 ~/ghq/github.com/efoo-team/skills/scripts/check-skills.py --only frontmatter --skills-dir <repo>/.agents/skills で frontmatter lint を行う（いずれも cwd に依存しない絶対パスで実行する。registration.md §7 と同一）。類似度警告が出たら統合を再検討し、統合しないなら AGENTS.md「統合しない判断の記録」節に根拠を登記する
2. 発火テスト: auto スキルは、発火すべきクエリと紛らわしい near-miss クエリを新しいセッション（またはサブエージェント）で投げて発火を確認する（authoring-insights.md §5）。explicit-only スキルは /<name> 起動と Gate の動作を確認する。同一セッションでの自己確認は発火テストにならない（スキルを書いたコンテキストが残っているため）
3. 可能なら eval を先に用意する: スキルなしで代表タスクを走らせた失敗（gap）を記録し、スキルありでその gap が埋まることを確認する（Phase 1 で確認した「出力が客観検証可能か」に応じて定量/定性を選ぶ。authoring-insights.md §6）。複数スキルを並行して作らず、1本ずつ検証する。確認できない項目は「残タスク」として明示する
4. registration.md §8 のテンプレートで完成報告を行う

重要な制約

• Phase 1 のヒアリングを省略しない。引数で情報が全て与えられているように見えても、理解した内容を要約提示して合意を得てから進む
• 各 Gate でユーザーの明確な回答を得るまで次の Phase に進まない。質問内容自体への指摘があった場合は、その内容を踏まえて質問を再検討する
• skill-authoring.md の原則文を新しいスキルへコピーしない（原則は適用するものであり、コピーは正本との drift の原因になる）
• ~/.agents/skills/ の実体を直接編集しない（配布先であり、次回 setup で消える）
• 検証（check-skills.py・発火テスト）未実施のまま「完成」と報告しない
• 推測で埋めない。不明な点は「不明」と明記してユーザーに確認する