ディレクトリ名も仕様のうち
frontmatter の name は親ディレクトリ名と一致していなければならず、スキルの改名は両方の改名を意味します。ここが最も多く破られる制約で、原因はたいてい、フォルダを複製して中のファイルだけを書き換えることです。結果としてスキルは検証に落ちるか無視されますが、その理由は出力のどこにも現れません。
プロジェクト単位とユーザー単位
プロジェクトに置いたスキルはリポジトリとともに動くので、クローンした人は同じ指示と同じレビュー履歴を受け取ります。ユーザー設定に置いたスキルは、どのプロジェクトでも付いてきます。特定のコードベースに属する取り決めはそのコードベースへ、あなた個人の作法はユーザー単位へ置いてください。
サブディレクトリの役割
SKILL.md には frontmatter と指示本体が入ります。scripts/ にはエージェントが実行しうるコード、references/ にはタスクが必要としたときだけ読み込まれる資料、assets/ にはテンプレート、画像、データファイルを置きます。ファイル参照は SKILL.md から一階層までに保ち、経路を何度もたどらせないでください。