create-repo-skill

リポジトリスキルを作成する

レイアウト（不変条件）

• .agents/skills/<kebab-name>/SKILL.md が、すべてのスキルの唯一の正規配置先です — 顧客がインストールする公開プロダクトスキル（SEO ワークフロー）も、内部リポジトリスキル（merge-ready、papercuts、このスキルのようなエージェントのワークフロー）も同様です。ユーザーは npx skills add every-app/open-seo を使って、このツリーからインストールします。
• .claude/skills/ に置くのは .agents/skills/ 内へのシンボリックリンクのみです — このリポジトリで作業する Claude Code エージェントが自動読み込みするスキルごとに 1 つ作成します。ファイルをコピーしてはいけません。.agents/skills/ は Prettier の対象外（ベンダー提供スキルはハッシュで固定）ですが、.claude/skills/ は対象です。そのため、コピーすると .claude 側で再フォーマットされ、ツリー間に差異が生じます。シンボリックリンクをルールにする前に、実際に 3 つのスキルでこの問題が起きました。prettier --check . はシンボリックリンクをたどらないため、シンボリックリンクは構造上、常に正規のソースとバイト単位で同一になります。
• ベンダー提供スキル（外部由来）は skills-lock.json でハッシュ固定されます（初回のベンダー取り込み時に skills CLI が作成します）。ベンダー提供スキルの内容を手作業で編集してはいけません。ロックハッシュを有効に保つため、skills CLI で再度取り込んでください。
• .agents/skills/** は レビュー管理プレーン（AGENTS.md を参照）の一部です。変更には CODEOWNERS による明示的なメンテナーのレビューが必要です。変更はブランチで行い、PR で明記してください。スキルの編集を付随的な変更として扱ってはいけません。

スキルの作成

1. mkdir .agents/skills/<kebab-name> を実行し、次のフロントマターを含む SKILL.md を作成します。

   ---
   name: <kebab-name>            # must match the directory name
   description: <what it does + explicit "use when ..." triggers>
   metadata:
     internal: true              # ONLY for internal repo skills — omit for product skills
   ---
   

2. スキルの種類を決めます。

   • 内部リポジトリスキル（エージェント／開発ワークフロー）：metadata.internal: true を設定します。公開されている場所には登録しないでください。リポジトリのエージェントに自動読み込みさせる場合は、ミラー用のシンボリックリンクを追加します。

     ln -s ../../.agents/skills/<name> .claude/skills/<name>
     

   • 公開プロダクトスキル（顧客向けの SEO ワークフロー）：internal フラグは付けません。通常、.claude/skills のシンボリックリンクも作成しません（リポジトリのエージェントに顧客向けのワークフローは不要です）。公開スキルは、ライブのアプリ内エージェントである SAM に自動配信されます。判定はフェイルオープンのため、internal: true がないと、リポジトリ開発向けの手順がエンドユーザーに配信されます。スキルに必要なセクションを含む標準の「Project context」前置きを用意し（seo-audit など、同階層のスキルを参考にします）、ユーザーがスキルを見つけるあらゆる場所に登録します。

     • src/server/features/sam/samSkills.test.ts — 固定された公開スキル一覧に名前を追加します（追加しない場合はテストが失敗します。この失敗がガードになります）。
     • web/content/docs/skills/<name>.mdx — ドキュメントページを作成します（competitor-analysis.mdx など、同階層のページを参考に、機能、使用するタイミング、得られる内容、最良の結果を得る方法を記載します）。
     • web/content/docs/skills/index.md — 適切なワークフローセクションに項目を追加します。
     • web/content/docs/skills/meta.json — ナビゲーション項目を追加します。
     • src/routes/_app/ai.tsx — SKILL_NAMES に追加します。
     • .agents/skills/seo-coach/SKILL.md — 「What each workflow does」の一覧に1行追加します。
     • plugins/openseo/skills/<name> — scripts/sync-plugin-skills.mjs の skills リストにスキルを追加し、pnpm sync-plugin-skills を実行します（このディレクトリにはシンボリックリンクではなく実際のコピーを置きます。Claude Code プラグインと Codex プラグインはここからバンドルされ、Codex のインストーラーはシンボリックリンクされたファイルを黙ってスキップするため、シンボリックリンクにするとスキルのないプラグインが配信されます）。pnpm ci:check は同期を再実行し、差分があると失敗するため、ここで更新を忘れても検出されます。ただし、以下のスキル数と一覧は文章でありチェックされないため、手動で更新してください。両方の plugins/openseo/*/plugin.json の description フィールド、Codex マニフェストの interface.longDescription、および web/content/docs/claude-code-plugin.md と web/content/docs/codex-plugin.md のスキル一覧です。
     • 任意：マーケティングやセットアップの掲載に適している場合は、web/src/lib/feature-pages.ts と web/content/docs/skills/setup.md も更新します。

3. スキルが MCP ツールを参照する場合は、正確なツール名を使用し、src/server/mcp/server.ts と同期させます。スキル内のツール名は、それに従うエージェントにとって重要です。公開スキルの場合は、src/server/features/sam/samChatTools.ts も確認します。SAM が使うツールセットは厳選された一部であり、SAM が持たないツールを指定するスキルの手順は、アプリ内エージェントで行き詰まります。

4. pnpm format:write を実行します（ドキュメントページは対象ですが、.agents/skills 自体は意図的に対象外です）。その後、コミットします。公開スキルの文章には、openseo-review-web-content の基準を適用します。

同期チェック（判断に迷った場合、およびスキルを変更した後に実行）

for d in .claude/skills/*/; do n=$(basename "$d")
  [ -L "${d%/}" ] || echo "DRIFT RISK — not a symlink: $n"
  [ -e ".agents/skills/$n" ] || echo "BROKEN — no canonical source: $n"
done

検出された項目があれば、正規のコンテンツを .agents/skills/<name>/ に移します（違いを意図的に調整し、まず両方の差分を確認してください。新しい意図を優先します）。.claude のコピーを削除し、シンボリックリンクに置き換えます。