Skip to content

gwt-spec: Skill契約・Lint・デュアルプラグイン配布 #160

@akiojin

Description

@akiojin

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-toolsEdit, 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, Globunity-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. 1 文目: <Verb> <object> with unity-cli. 形式の What 文
  2. 2 文目以降に Use when を 1 回以上
  3. 2 文目以降に Do not use (または Not for ) を 1 回以上
  4. 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

実装フェーズ

  1. Linter コア実装 (T-2 〜 T-5): TDD で R01 〜 R22 を順次積む。Rust モジュール src/skills/、CLI サブコマンド src/bin/unity-cli/cli/skills.rs、統合テスト tests/skills_lint.rs
  2. 既存 14 skill 移行 (T-6): frontmatter / description / SKILL.md 本文 / references を新契約へ書き換え。
  3. gh-skills-sync 退避 (T-7): dev-skills/ へ移動、シンボリックリンク再配線。
  4. Codex プラグイン配置 (T-8): .codex-plugin/plugin.json.agents/skills/.agents/plugins/marketplace.json を新設。.codex/ 削除。
  5. Claude プラグイン調整 (T-9): version bump、skills フィールド明示。
  6. CONTRIBUTING / docs (T-10): 開発者向けドキュメント整備。
  7. CI ゲート (T-11): .github/workflows/ に skill lint ステップ追加。
  8. 最終検証 (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)

  • src/skills/mod.rs に型定義 (Skill, Frontmatter, Violation, Severity)
  • tests/fixtures/skills/good/ / tests/fixtures/skills/bad/ 作成
  • R01 〜 R06 のテストを RED で追加
  • loader + R01 〜 R06 実装で GREEN

T-3. Linter description ルール

  • R07 〜 R12 のテストを RED で追加
  • R07 〜 R12 実装で GREEN
  • 三人称チェック (R09) は正規表現集合で誤検出を最小化

T-4. Linter body / references / symlink ルール

  • R13 〜 R22 のテストを RED で追加
  • R13 〜 R22 実装で GREEN
  • symlink 検証は一時ディレクトリでユニットテスト

T-5. CLI サブコマンド統合

  • unity-cli skills lint 実装 (src/bin/unity-cli/cli/skills.rs)
  • --fix / --format / --severity / --root フラグ
  • 統合テスト tests/skills_lint.rs

T-6. 既存 14 skill の契約移行

  • metadata.triggers / metadata.siblings 追加
  • unity-cli-usageuser-invocable: false
  • description を新文体へ書き換え
  • SKILL.md 本文を 5 セクション構造へ再編
  • references/runtime-checklist.md を全 skill にコピー
  • 100 行超の references に目次追加
  • unity-csharp-editallowed-toolsEdit, Write 追加
  • version を 0.3.0 以上に bump

T-7. gh-skills-sync 退避

  • dev-skills/gh-skills-sync/ へ移動
  • .claude/skills/gh-skills-syncdev-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.ymlcargo run -- skills lint --severity warning 追加
  • .github/workflows/release.ymlcargo run -- skills lint --severity error 追加
  • 本 PR マージ時に PR 用 severity を error へ切り替え

T-12. 最終検証

  • cargo fmt --all -- --check
  • cargo clippy --all-targets -- -D warnings
  • cargo test --all-targets
  • cargo run -- skills lint --severity error が 0 を返す
  • symlink 健全性確認
  • Codex CLI で plugin 認識確認 (手動)

受け入れ基準

  • unity-cli skills lint --severity error が exit 0 かつ 0 violation
  • cargo test --all-targets が全 pass
  • 14 skill 全てが新契約準拠
  • .codex-plugin/plugin.json / .agents/skills/ / .agents/plugins/marketplace.json 作成済み
  • .codex/skills/ 削除済み
  • gh-skills-syncdev-skills/ へ退避済み
  • CONTRIBUTING.md と docs/skills.md 作成済み
  • CI で skill lint ステップが走る (PR=warning または error、release=error)
  • 本 Issue 本文の Tasks が実態と同期

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.rsCommand::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 の誤検出で開発が止まらない

参照

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions