Spec
Background
ドメイン仕様書: Claude Code / Codex Skill 契約・Lint・デュアルプラグイン配布
作成日: 2026-04-08
ステータス: active
関連 Issue: #145 (CLI 基盤・アーキテクチャ — スキル導線の親仕様)
unity-cli リポジトリ配下の Claude Code Skill を Anthropic 公式ベストプラクティスに準拠させ、機械検証可能な「Skill 契約 v1」と Rust 製 linter (unity-cli skills lint) を導入する。同時に、Codex CLI が 2025/12 に公開した正式 plugin 仕様 (.codex-plugin/plugin.json / .agents/skills/ / .agents/plugins/marketplace.json) に対応し、Claude Code と Codex の両方で plugin 形式として配布できる構造へ移行する。既存 14 個の Unity 向け skill は本 Issue のスコープで一括移行する。開発専用 skill (gh-skills-sync) は配布プラグインから除外し dev-skills/ へ退避する。
| 課題 |
現状 |
影響 |
| 発火制御が目視ベース |
description の書き方・語彙・sibling 間の境界が skill ごとに不揃い |
LLM が誤発火 / 未発火し、ユーザー体験が劣化 |
| SKILL.md 本文の構造不統一 |
見出し構成・references 配置・allowed-tools がスキルごとにばらつき |
progressive disclosure が機能せず、メンテ性低下 |
| Codex 対応が非公式 |
.codex/skills/ という公式規約外パスに素の skill 集合を配置 |
Codex の plugin marketplace から認識されない |
| 開発用 skill の混入 |
gh-skills-sync (unity-cli リポジトリ開発用) が配布プラグインに含まれている |
エンドユーザーに無関係な skill が配布される |
Ubiquitous Language
TODO
User Stories
TODO
Acceptance Scenarios
TODO
Edge Cases
TODO
Functional Requirements
TODO
Non-Functional Requirements
TODO
Success Criteria
TODO
Domain-Specific Details
対象範囲
対象 skill (14 個 + foundation 1)
| skill 名 |
category |
foundation |
unity-cli-usage |
foundation |
✓ (user-invocable: false) |
unity-addressables |
assets |
|
unity-asset-management |
assets |
|
unity-csharp-edit |
code |
(allowed-tools に Edit, Write 追加) |
unity-csharp-navigate |
code |
|
unity-editor-tools |
editor |
|
unity-gameobject-edit |
scenes |
|
unity-input-system |
input |
|
unity-playmode-testing |
testing |
|
unity-prefab-workflow |
prefabs |
|
unity-scene-create |
scenes |
|
unity-scene-inspect |
scenes |
|
unity-ui-automation |
ui |
|
対象外
gh-skills-sync (unity-cli リポジトリの開発用 skill)。本 Issue で dev-skills/ へ退避し、配布プラグインから除外。
Skill 契約 v1
命名
- skill 名は
unity-<domain>-<action> 名詞句形式 (現行維持)。
- ディレクトリ名 = frontmatter
name (kebab-case、最大 64 文字)。
- 予約語
claude / anthropic を含まない。
frontmatter 必須フィールド
| フィールド |
型 |
ルール |
name |
string |
ディレクトリ名と一致 |
description |
string |
ハード上限 1024 文字。先頭 250 に metadata.triggers のうち 1 語以上を含むこと。三人称・命令形 (Verb + object)。一人称/二人称 (I , we , you can , お手伝いできます 等) 禁止 |
allowed-tools |
string |
基本集合: Bash(unity-cli:*), Read, Grep, Glob。unity-csharp-edit のみ Edit, Write 追加可 |
metadata.author |
string |
非空 |
metadata.version |
string |
SemVer (移行後は 0.3.0 以上) |
metadata.category |
enum |
foundation / scenes / assets / code / editor / input / testing / prefabs / ui |
metadata.triggers |
string[] |
1 件以上、単数形・小文字、重複なし |
metadata.siblings |
string[] |
0 件以上、実在する skill 名のみ |
description 文体構造 (ソフト規約)
- 1 文目:
<Verb> <object> with unity-cli. 形式の What 文
- 2 文目以降に
Use when を 1 回以上
- 2 文目以降に
Do not use (または Not for ) を 1 回以上
Do not use 側で metadata.siblings のうち少なくとも 1 つの skill 名を明示参照
例 (unity-prefab-workflow):
Manage Unity prefab assets with unity-cli. Use when the user asks to create a prefab from a scene object, open a prefab in edit mode, save prefab changes, or instantiate a prefab. Do not use for general scene object editing; use unity-gameobject-edit or unity-scene-create instead.
SKILL.md 本文 (progressive disclosure 2 層目)
- 上限: 500 行
- 必須 H2 見出し順序:
## Use When → ## Do Not Use When → ## Preferred Flow → ## Examples → ## References
## References は最低 1 個のリンクを含む
- ファイルリンクは SKILL.md から 1 層のみ (references 配下から別 references への相対リンク禁止)
- 100 行超の reference ファイルは冒頭 15 行以内に
## Table of Contents
- 時間依存記述 (
as of 2025-08, until next release) 禁止
- 全 skill に
references/runtime-checklist.md (unity-cli 接続確認 / インスタンス選択 / install mode 判別の共通チェックリスト) を必須化
Linter (unity-cli skills lint)
CLI 仕様
unity-cli skills lint [--fix] [--root <path>] [--format text|json] [--severity warning|error]
--root 省略時は CWD から repo root を探索し .claude-plugin/plugins/<plugin>/skills/ を自動検出
--severity 既定値: warning (PR 用)。release CI では error
- 終了コード: 成功=0、違反あり+severity=error で 1、I/O エラーで 2
--fix: 末尾改行・符号化・安全な三人称置換・シンボリックリンク再生成のみ
検証ルール (適用範囲 = unity-* プレフィックスの skill のみ)
| ID |
区分 |
内容 |
| R01 |
frontmatter |
必須フィールドの存在と型 |
| R02 |
frontmatter |
name がディレクトリ名と一致 |
| R03 |
frontmatter |
allowed-tools が許可集合の部分集合 |
| R04 |
frontmatter |
metadata.category が enum 値 |
| R05 |
frontmatter |
metadata.triggers 非空・単数形・小文字・重複なし |
| R06 |
frontmatter |
metadata.siblings の各エントリが実在 |
| R07 |
description |
長さ ≤ 1024 |
| R08 |
description |
先頭 250 に triggers の 1 語以上が出現 |
| R09 |
description |
一人称 / 二人称パターン不在 |
| R10 |
description |
Use when と Do not use の両方が出現 |
| R11 |
description |
siblings の少なくとも 1 つが description 本文に出現 |
| R12 |
description |
sibling の双方向性 (A→B なら B→A) |
| R13 |
SKILL.md body |
≤ 500 行 |
| R14 |
SKILL.md body |
必須 H2 見出し 5 個が順序通り存在 |
| R15 |
SKILL.md body |
## References に 1 個以上のリンク |
| R16 |
SKILL.md body |
時間依存語彙不在 |
| R17 |
references |
references/runtime-checklist.md 存在 |
| R18 |
references |
100 行超の reference ファイルは冒頭 15 行以内に ## Table of Contents |
| R19 |
references |
reference ファイル間のリンクなし (1 層ネスト) |
| R20 |
symlinks |
.claude/skills/<name> が正本を指す |
| R21 |
symlinks |
.agents/skills/<name> が正本を指す |
| R22 |
trigger 衝突 |
同一 trigger を複数 skill が持つ場合、双方の metadata.siblings に互いが含まれる |
デュアルプラグイン配布
物理配置
<repo>/
├── .claude-plugin/
│ ├── marketplace.json # 既存
│ └── plugins/unity-cli/
│ ├── plugin.json # version 0.2.0 / skills field 明示
│ ├── CONTRIBUTING.md # 新規
│ └── skills/ # 正本 (物理実体)
│ ├── unity-addressables/
│ ├── unity-asset-management/
│ ├── unity-cli-usage/ # user-invocable: false
│ ├── unity-csharp-edit/ # allowed-tools に Edit, Write
│ ├── unity-csharp-navigate/
│ ├── unity-editor-tools/
│ ├── unity-gameobject-edit/
│ ├── unity-input-system/
│ ├── unity-playmode-testing/
│ ├── unity-prefab-workflow/
│ ├── unity-scene-create/
│ ├── unity-scene-inspect/
│ └── unity-ui-automation/
├── .codex-plugin/
│ └── plugin.json # 新規 (Claude 正本の skills を参照)
├── .agents/
│ ├── skills/ # symlink → .claude-plugin/.../skills/
│ └── plugins/
│ └── marketplace.json # 新規 (Codex marketplace)
├── .claude/skills/ # symlink 再生成
├── .codex/ # 削除
├── dev-skills/gh-skills-sync/ # 配布対象外へ退避
└── docs/skills.md # 新規 (ルール根拠・対応表)
.codex-plugin/plugin.json 最小スキーマ
{
"name": "unity-cli",
"version": "0.2.0",
"description": "Codex plugin providing workflow-oriented skills for Rust-based unity-cli automation.",
"author": { "name": "akiojin", "url": "https://github.com/akiojin" },
"skills": "../.claude-plugin/plugins/unity-cli/skills/",
"interface": {
"displayName": "Unity CLI",
"shortDescription": "Unity Editor automation via unity-cli",
"category": "Productivity",
"capabilities": ["skills"]
}
}
CI / 品質ゲート
.github/workflows/ci.yml: cargo run -- skills lint --severity warning (PR 段階) → 移行 PR マージ後に --severity error へ昇格
.github/workflows/release.yml: cargo run -- skills lint --severity error
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
Plan
実装フェーズ
- Linter コア実装 (T-2 〜 T-5): TDD で R01 〜 R22 を順次積む。Rust モジュール
src/skills/、CLI サブコマンド src/bin/unity-cli/cli/skills.rs、統合テスト tests/skills_lint.rs。
- 既存 14 skill 移行 (T-6): frontmatter / description / SKILL.md 本文 / references を新契約へ書き換え。
- gh-skills-sync 退避 (T-7):
dev-skills/ へ移動、シンボリックリンク再配線。
- Codex プラグイン配置 (T-8):
.codex-plugin/plugin.json、.agents/skills/、.agents/plugins/marketplace.json を新設。.codex/ 削除。
- Claude プラグイン調整 (T-9): version bump、skills フィールド明示。
- CONTRIBUTING / docs (T-10): 開発者向けドキュメント整備。
- CI ゲート (T-11):
.github/workflows/ に skill lint ステップ追加。
- 最終検証 (T-12): fmt / clippy / test / lint / symlink integrity。
実装単位
単一 PR で完結させる。本 PR 内で linter 実装と契約移行を同時に行い、最後に CI severity を error へ昇格する。これにより rollout の中間状態 (linter あるけど skill 未移行) を避ける。
Tasks
T-1. SPEC Issue 作成
T-2. Linter ドメインモデル (RED → GREEN)
T-3. Linter description ルール
T-4. Linter body / references / symlink ルール
T-5. CLI サブコマンド統合
T-6. 既存 14 skill の契約移行
T-7. gh-skills-sync 退避
T-8. Codex プラグイン配置
T-9. Claude プラグイン調整
T-10. CONTRIBUTING / docs
T-11. CI / ゲート
T-12. 最終検証
受け入れ基準
TDD
フェーズ 1: Linter コア (T-2 〜 T-5)
各ルール R01 〜 R22 を 1 ルール = 1 RED テスト + 1 GREEN 実装 + 1 REFACTOR で積む。
- RED:
tests/fixtures/skills/bad/R<xx>/ に最小違反例を配置し、ルール実行が Violation { rule: "Rxx", .. } を返すことを失敗状態で assert
- GREEN: ルール実装を最小コードで追加し、該当テストのみ通過させる (他ルールは暫定スタブ)
- REFACTOR: 共通処理 (YAML 読み込み、Markdown パース) をヘルパーに集約
完了条件: cargo test skills::rules:: が 22 ケース以上 pass
フェーズ 2: CLI e2e (T-5)
- RED:
tests/skills_lint.rs で Command::cargo_bin("unity-cli")?.args(["skills", "lint", "--root", "tests/fixtures/skills/good"]) が exit 0、bad/ なら exit 1 を assert
- GREEN:
cli/skills.rs 実装
- REFACTOR: 出力フォーマッター (text / json) を独立モジュール化
フェーズ 3: 契約移行回帰 (T-6)
- 14 skill それぞれについて
cargo run -- skills lint --root .claude-plugin/plugins/unity-cli/skills/<name> が --severity error で exit 0 を返すことを 1 skill 1 テストケースで列挙
tests/skills_contract_migration.rs に 14 個のテストを個別記述 (ループ禁止、どれが落ちたか即時把握)
フェーズ 4: 対称性 / symlink (T-7, T-8)
tests/skills_symlink.rs:
.claude/skills/unity-<name> が正本を指す (canonicalize 比較)
.agents/skills/unity-<name> が正本を指す
gh-skills-sync が配布 skill ディレクトリ配下に存在しない
Verification
# 1. 品質ゲート
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
# 2. Linter 実行
cargo run -- skills lint --severity error --format text
cargo run -- skills lint --severity error --format json | jq '. | length == 0'
# 3. シンボリックリンク健全性
ls -la .claude/skills/ | grep unity-
ls -la .agents/skills/ | grep unity-
test ! -e .codex/skills
test ! -e .claude-plugin/plugins/unity-cli/skills/gh-skills-sync
test -d dev-skills/gh-skills-sync
# 4. プラグインマニフェスト整合性
jq '.version' .claude-plugin/plugins/unity-cli/plugin.json
jq '.version' .codex-plugin/plugin.json
jq '.plugins[].name' .agents/plugins/marketplace.json
# 5. Unity E2E 疎通
unity-cli --version
unity-cli system ping
ロールバック方針
- 単一 PR 構成のため、問題発生時は PR を revert すれば旧状態に戻る
.codex/skills/ 削除は本 PR 内でのみ行い、Codex 側で認識不能になった場合は併存形 (.codex/skills/ 復元 + .agents/skills/ 残存) へ一時退避可能
- linter の CI severity は warning でスタート可能なため、初回 PR の誤検出で開発が止まらない
参照
Spec
Background
ドメイン仕様書: Claude Code / Codex Skill 契約・Lint・デュアルプラグイン配布
作成日: 2026-04-08
ステータス: active
関連 Issue: #145 (CLI 基盤・アーキテクチャ — スキル導線の親仕様)
unity-cliリポジトリ配下の Claude Code Skill を Anthropic 公式ベストプラクティスに準拠させ、機械検証可能な「Skill 契約 v1」と Rust 製 linter (unity-cli skills lint) を導入する。同時に、Codex CLI が 2025/12 に公開した正式 plugin 仕様 (.codex-plugin/plugin.json/.agents/skills//.agents/plugins/marketplace.json) に対応し、Claude Code と Codex の両方で plugin 形式として配布できる構造へ移行する。既存 14 個の Unity 向け skill は本 Issue のスコープで一括移行する。開発専用 skill (gh-skills-sync) は配布プラグインから除外しdev-skills/へ退避する。.codex/skills/という公式規約外パスに素の skill 集合を配置gh-skills-sync(unity-cli リポジトリ開発用) が配布プラグインに含まれているUbiquitous Language
TODO
User Stories
TODO
Acceptance Scenarios
TODO
Edge Cases
TODO
Functional Requirements
TODO
Non-Functional Requirements
TODO
Success Criteria
TODO
Domain-Specific Details
対象範囲
対象 skill (14 個 + foundation 1)
unity-cli-usageuser-invocable: false)unity-addressablesunity-asset-managementunity-csharp-editallowed-toolsにEdit, Write追加)unity-csharp-navigateunity-editor-toolsunity-gameobject-editunity-input-systemunity-playmode-testingunity-prefab-workflowunity-scene-createunity-scene-inspectunity-ui-automation対象外
gh-skills-sync(unity-cli リポジトリの開発用 skill)。本 Issue でdev-skills/へ退避し、配布プラグインから除外。Skill 契約 v1
命名
unity-<domain>-<action>名詞句形式 (現行維持)。name(kebab-case、最大 64 文字)。claude/anthropicを含まない。frontmatter 必須フィールド
namedescriptionmetadata.triggersのうち 1 語以上を含むこと。三人称・命令形 (Verb + object)。一人称/二人称 (I,we,you can,お手伝いできます等) 禁止allowed-toolsBash(unity-cli:*), Read, Grep, Glob。unity-csharp-editのみEdit, Write追加可metadata.authormetadata.versionmetadata.categoryfoundation/scenes/assets/code/editor/input/testing/prefabs/uimetadata.triggersmetadata.siblingsdescription 文体構造 (ソフト規約)
<Verb> <object> with unity-cli.形式の What 文Use whenを 1 回以上Do not use(またはNot for) を 1 回以上Do not use側でmetadata.siblingsのうち少なくとも 1 つの skill 名を明示参照例 (
unity-prefab-workflow):SKILL.md 本文 (progressive disclosure 2 層目)
## Use When→## Do Not Use When→## Preferred Flow→## Examples→## References## Referencesは最低 1 個のリンクを含む## Table of Contentsas of 2025-08,until next release) 禁止references/runtime-checklist.md(unity-cli 接続確認 / インスタンス選択 / install mode 判別の共通チェックリスト) を必須化Linter (
unity-cli skills lint)CLI 仕様
--root省略時は CWD から repo root を探索し.claude-plugin/plugins/<plugin>/skills/を自動検出--severity既定値:warning(PR 用)。release CI ではerror--fix: 末尾改行・符号化・安全な三人称置換・シンボリックリンク再生成のみ検証ルール (適用範囲 =
unity-*プレフィックスの skill のみ)nameがディレクトリ名と一致allowed-toolsが許可集合の部分集合metadata.categoryが enum 値metadata.triggers非空・単数形・小文字・重複なしmetadata.siblingsの各エントリが実在Use whenとDo not useの両方が出現## Referencesに 1 個以上のリンクreferences/runtime-checklist.md存在## Table of Contents.claude/skills/<name>が正本を指す.agents/skills/<name>が正本を指すmetadata.siblingsに互いが含まれるデュアルプラグイン配布
物理配置
.codex-plugin/plugin.json最小スキーマ{ "name": "unity-cli", "version": "0.2.0", "description": "Codex plugin providing workflow-oriented skills for Rust-based unity-cli automation.", "author": { "name": "akiojin", "url": "https://github.com/akiojin" }, "skills": "../.claude-plugin/plugins/unity-cli/skills/", "interface": { "displayName": "Unity CLI", "shortDescription": "Unity Editor automation via unity-cli", "category": "Productivity", "capabilities": ["skills"] } }CI / 品質ゲート
.github/workflows/ci.yml:cargo run -- skills lint --severity warning(PR 段階) → 移行 PR マージ後に--severity errorへ昇格.github/workflows/release.yml:cargo run -- skills lint --severity errorcargo fmt --all -- --checkcargo clippy --all-targets -- -D warningscargo test --all-targetsPlan
実装フェーズ
src/skills/、CLI サブコマンドsrc/bin/unity-cli/cli/skills.rs、統合テストtests/skills_lint.rs。dev-skills/へ移動、シンボリックリンク再配線。.codex-plugin/plugin.json、.agents/skills/、.agents/plugins/marketplace.jsonを新設。.codex/削除。.github/workflows/に skill lint ステップ追加。実装単位
単一 PR で完結させる。本 PR 内で linter 実装と契約移行を同時に行い、最後に CI severity を error へ昇格する。これにより rollout の中間状態 (linter あるけど skill 未移行) を避ける。
Tasks
T-1. SPEC Issue 作成
T-2. Linter ドメインモデル (RED → GREEN)
src/skills/mod.rsに型定義 (Skill,Frontmatter,Violation,Severity)tests/fixtures/skills/good//tests/fixtures/skills/bad/作成T-3. Linter description ルール
T-4. Linter body / references / symlink ルール
T-5. CLI サブコマンド統合
unity-cli skills lint実装 (src/bin/unity-cli/cli/skills.rs)--fix/--format/--severity/--rootフラグtests/skills_lint.rsT-6. 既存 14 skill の契約移行
metadata.triggers/metadata.siblings追加unity-cli-usageにuser-invocable: falsereferences/runtime-checklist.mdを全 skill にコピーunity-csharp-editのallowed-toolsにEdit, Write追加T-7. gh-skills-sync 退避
dev-skills/gh-skills-sync/へ移動.claude/skills/gh-skills-syncをdev-skills/へ向け直し.codex/skills/gh-skills-syncを削除 (新.agents/skills/には含めない)docs/development.mdに開発 skill であることを明記T-8. Codex プラグイン配置
.codex-plugin/plugin.json作成.agents/skills/を正本へのシンボリックリンクとして作成.agents/plugins/marketplace.json作成.codex/skills/削除scripts/static-skill-contract-check.shを廃止 (存在する場合)T-9. Claude プラグイン調整
.claude-plugin/plugins/unity-cli/plugin.jsonを 0.2.0 へ bump、skills: "./skills/"明示.claude-plugin/marketplace.jsonの参照 version 更新T-10. CONTRIBUTING / docs
.claude-plugin/plugins/unity-cli/CONTRIBUTING.md作成docs/skills.md作成CLAUDE.mdの「スキルアーキテクチャ」章を更新T-11. CI / ゲート
.github/workflows/ci.ymlにcargo run -- skills lint --severity warning追加.github/workflows/release.ymlにcargo run -- skills lint --severity error追加errorへ切り替えT-12. 最終検証
cargo fmt --all -- --checkcargo clippy --all-targets -- -D warningscargo test --all-targetscargo run -- skills lint --severity errorが 0 を返す受け入れ基準
unity-cli skills lint --severity errorが exit 0 かつ 0 violationcargo test --all-targetsが全 pass.codex-plugin/plugin.json/.agents/skills//.agents/plugins/marketplace.json作成済み.codex/skills/削除済みgh-skills-syncがdev-skills/へ退避済みTDD
フェーズ 1: Linter コア (T-2 〜 T-5)
各ルール R01 〜 R22 を 1 ルール = 1 RED テスト + 1 GREEN 実装 + 1 REFACTOR で積む。
tests/fixtures/skills/bad/R<xx>/に最小違反例を配置し、ルール実行がViolation { rule: "Rxx", .. }を返すことを失敗状態で assert完了条件:
cargo test skills::rules::が 22 ケース以上 passフェーズ 2: CLI e2e (T-5)
tests/skills_lint.rsでCommand::cargo_bin("unity-cli")?.args(["skills", "lint", "--root", "tests/fixtures/skills/good"])が exit 0、bad/なら exit 1 を assertcli/skills.rs実装フェーズ 3: 契約移行回帰 (T-6)
cargo run -- skills lint --root .claude-plugin/plugins/unity-cli/skills/<name>が--severity errorで exit 0 を返すことを 1 skill 1 テストケースで列挙tests/skills_contract_migration.rsに 14 個のテストを個別記述 (ループ禁止、どれが落ちたか即時把握)フェーズ 4: 対称性 / symlink (T-7, T-8)
tests/skills_symlink.rs:.claude/skills/unity-<name>が正本を指す (canonicalize 比較).agents/skills/unity-<name>が正本を指すgh-skills-syncが配布 skill ディレクトリ配下に存在しないVerification
ロールバック方針
.codex/skills/削除は本 PR 内でのみ行い、Codex 側で認識不能になった場合は併存形 (.codex/skills/復元 +.agents/skills/残存) へ一時退避可能参照