ae-agent-skills 0.2.4 → 0.2.5

package/README.ja.md

@@ -15,6 +15,7 @@ npx ae-agent-skills install
 1. `--agent` 未指定なら、`codex` / `gemini` / `both` の選択を表示します。
 2. 署名済み ZXP を `UPIA` または `ExManCmd` でインストールします。
 3. `ae-cli` と agent skill をインストールします。
+4. `~/ae-agent-skills/` を初期化し、`work/`・`done/`・`scene.schema.json`・`references/` を配置します。
 
 ## エージェントで実行
 

package/README.md

@@ -15,6 +15,7 @@ What happens:
 1. The installer asks which agent to configure (`codex` / `gemini` / `both`) if `--agent` is omitted.
 2. It installs the signed ZXP extension via `UPIA` or `ExManCmd`.
 3. It installs `ae-cli` and agent skills.
+4. It initializes `~/ae-agent-skills/` with `work/`, `done/`, `scene.schema.json`, and `references/`.
 
 ## Run with your agent
 

package/bin/ae-agent-setup.mjs

@@ -8,10 +8,17 @@ import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
 const DEFAULT_REPO = 'yumehiko/ae-agent-skills';
+const AGENT_WORKSPACE_NAME = 'ae-agent-skills';
 const SKILL_SOURCES = [
   { sourceName: 'aftereffects-cli.SKILL.md', destinationName: 'aftereffects-cli' },
   { sourceName: 'aftereffects-declarative.SKILL.md', destinationName: 'aftereffects-declarative' },
 ];
+const WORKSPACE_RESOURCE_SOURCES = [
+  { source: ['schemas', 'scene.schema.json'], destination: ['scene.schema.json'] },
+  { source: ['examples', 'scene.example.json'], destination: ['references', 'scene.example.json'] },
+  { source: ['docs', 'cli.ja.md'], destination: ['references', 'cli.ja.md'] },
+  { source: ['docs', 'cli.md'], destination: ['references', 'cli.md'] },
+];
 
 function printHelp() {
   console.log(`ae-agent-setup
@@ -255,6 +262,29 @@ function installSkills(agent) {
   }
 }
 
+function setupAgentWorkspace() {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const workspaceRoot = path.join(os.homedir(), AGENT_WORKSPACE_NAME);
+  const workDir = path.join(workspaceRoot, 'work');
+  const doneDir = path.join(workspaceRoot, 'done');
+  const refsDir = path.join(workspaceRoot, 'references');
+
+  fs.mkdirSync(workDir, { recursive: true });
+  fs.mkdirSync(doneDir, { recursive: true });
+  fs.mkdirSync(refsDir, { recursive: true });
+
+  for (const resource of WORKSPACE_RESOURCE_SOURCES) {
+    const source = path.join(root, ...resource.source);
+    const destination = path.join(workspaceRoot, ...resource.destination);
+    if (!fs.existsSync(source)) {
+      throw new Error(`Workspace resource not found: ${source}`);
+    }
+    fs.copyFileSync(source, destination);
+  }
+
+  console.log(`Prepared workspace: ${workspaceRoot}`);
+}
+
 function installCli(repo) {
   if (!commandExists('python3')) {
     throw new Error('python3 is required to install ae-cli.');
@@ -272,6 +302,7 @@ function installCli(repo) {
 
 async function installCommand(opts) {
   console.log('Starting ae-agent setup...');
+  setupAgentWorkspace();
 
   const agent = await resolveAgent(opts.agent);
   console.log(`Selected agent target: ${agent}`);
@@ -308,6 +339,7 @@ async function installCommand(opts) {
   console.log('  1) Fully restart After Effects.');
   console.log('  2) Open the panel: Window > Extensions (Beta) > ae-agent-skill.');
   console.log('  3) Run: ae-cli health');
+  console.log(`  4) Use workspace: ${path.join(os.homedir(), AGENT_WORKSPACE_NAME)}`);
 }
 
 async function main() {

package/docs/cli.ja.md

@@ -0,0 +1,49 @@
+# CLI利用方法
+
+## 基本確認
+
+```bash
+ae-cli --help
+ae-cli health
+ae-cli layers
+```
+
+`ae-cli` が `PATH` にない場合:
+
+```bash
+PYTHONPATH=src python3 -m ae_cli.main --help
+```
+
+デフォルトのブリッジURL:
+
+- `AE_BRIDGE_URL` があればそれを使用
+- なければ `http://127.0.0.1:8080`
+
+## よく使うコマンド
+
+```bash
+ae-cli list-comps
+ae-cli create-comp --name "Main" --width 1920 --height 1080 --duration 8 --frame-rate 30
+ae-cli set-active-comp --comp-name "Main"
+ae-cli selected-properties
+ae-cli expression-errors
+```
+
+## 宣言的シーン適用
+
+```bash
+ae-cli apply-scene --scene-file examples/scene.example.json --validate-only
+ae-cli apply-scene --scene-file examples/scene.example.json
+ae-cli apply-scene --scene-file examples/scene.example.json --mode replace-managed
+ae-cli apply-scene --scene-file examples/scene.example.json --mode clear-all
+```
+
+スキーマ:
+
+- `schemas/scene.schema.json`
+
+`apply-scene` の mode:
+
+- `merge`（デフォルト）: upsertのみ
+- `replace-managed`: 不要な `aeSceneId:*` 管理レイヤーを削除して適用
+- `clear-all`: compを空にして適用

package/docs/cli.md

@@ -0,0 +1,49 @@
+# CLI Usage
+
+## Basic checks
+
+```bash
+ae-cli --help
+ae-cli health
+ae-cli layers
+```
+
+If `ae-cli` is not on your `PATH`:
+
+```bash
+PYTHONPATH=src python3 -m ae_cli.main --help
+```
+
+Default bridge URL:
+
+- `AE_BRIDGE_URL` if set
+- otherwise `http://127.0.0.1:8080`
+
+## Common commands
+
+```bash
+ae-cli list-comps
+ae-cli create-comp --name "Main" --width 1920 --height 1080 --duration 8 --frame-rate 30
+ae-cli set-active-comp --comp-name "Main"
+ae-cli selected-properties
+ae-cli expression-errors
+```
+
+## Declarative scene apply
+
+```bash
+ae-cli apply-scene --scene-file examples/scene.example.json --validate-only
+ae-cli apply-scene --scene-file examples/scene.example.json
+ae-cli apply-scene --scene-file examples/scene.example.json --mode replace-managed
+ae-cli apply-scene --scene-file examples/scene.example.json --mode clear-all
+```
+
+Schema:
+
+- `schemas/scene.schema.json`
+
+`apply-scene` modes:
+
+- `merge` (default): upsert only
+- `replace-managed`: remove unmanaged `aeSceneId:*` leftovers, then apply
+- `clear-all`: clear comp, then apply

package/docs/development.ja.md

@@ -0,0 +1,62 @@
+# 開発者向け情報
+
+## ローカル開発の前提
+
+- macOS
+- Adobe After Effects（CEP対応環境）
+- Python 3.10+
+
+## 未署名ローカル開発モード
+
+未署名拡張で開発する場合は `PlayerDebugMode=1` を有効化します。
+
+```bash
+defaults domains | tr ',' '\n' | rg 'com\.adobe\.CSXS\.'
+# 例: com.adobe.CSXS.11 の場合
+defaults write com.adobe.CSXS.11 PlayerDebugMode 1
+```
+
+設定後は After Effects を完全終了して再起動してください。
+
+## Python開発セットアップ
+
+```bash
+python3 -m pip install -e ".[dev]"
+PYTHONPATH=src pytest
+```
+
+## プロジェクト構成
+
+### Python CLI
+
+- `src/ae_cli/cli_parser.py`
+- `src/ae_cli/cli_runner.py`
+- `src/ae_cli/client.py`
+- `src/ae_cli/main.py`
+
+### ExtendScript host
+
+- `host/index.jsx`
+- `host/lib/common.jsx`
+- `host/lib/property_utils.jsx`
+- `host/lib/query_handlers.jsx`
+- `host/lib/mutation_handlers.jsx`
+- `host/lib/mutation_keyframe_handlers.jsx`
+- `host/lib/mutation_shape_handlers.jsx`
+- `host/lib/mutation_timeline_handlers.jsx`
+- `host/lib/mutation_layer_structure_handlers.jsx`
+- `host/lib/mutation_scene_handlers.jsx`
+
+### CEP panel client
+
+- `client/main.js`
+- `client/lib/runtime.js`
+- `client/lib/logging.js`
+- `client/lib/bridge_utils.js`
+- `client/lib/request_handlers_shape.js`
+- `client/lib/request_handlers_scene.js`
+- `client/lib/request_handlers_essential.js`
+- `client/lib/request_handlers_timeline.js`
+- `client/lib/request_handlers_layer_structure.js`
+- `client/lib/request_handlers.js`
+- `client/lib/server.js`

package/docs/development.md

@@ -0,0 +1,62 @@
+# Development
+
+## Local dev requirements
+
+- macOS
+- Adobe After Effects (CEP-capable)
+- Python 3.10+
+
+## Unsigned local dev mode
+
+For local unsigned extension workflows, enable `PlayerDebugMode=1`:
+
+```bash
+defaults domains | tr ',' '\n' | rg 'com\.adobe\.CSXS\.'
+# Example for com.adobe.CSXS.11
+defaults write com.adobe.CSXS.11 PlayerDebugMode 1
+```
+
+Then fully quit and relaunch After Effects.
+
+## Python dev setup
+
+```bash
+python3 -m pip install -e ".[dev]"
+PYTHONPATH=src pytest
+```
+
+## Project structure
+
+### Python CLI
+
+- `src/ae_cli/cli_parser.py`
+- `src/ae_cli/cli_runner.py`
+- `src/ae_cli/client.py`
+- `src/ae_cli/main.py`
+
+### ExtendScript host
+
+- `host/index.jsx`
+- `host/lib/common.jsx`
+- `host/lib/property_utils.jsx`
+- `host/lib/query_handlers.jsx`
+- `host/lib/mutation_handlers.jsx`
+- `host/lib/mutation_keyframe_handlers.jsx`
+- `host/lib/mutation_shape_handlers.jsx`
+- `host/lib/mutation_timeline_handlers.jsx`
+- `host/lib/mutation_layer_structure_handlers.jsx`
+- `host/lib/mutation_scene_handlers.jsx`
+
+### CEP panel client
+
+- `client/main.js`
+- `client/lib/runtime.js`
+- `client/lib/logging.js`
+- `client/lib/bridge_utils.js`
+- `client/lib/request_handlers_shape.js`
+- `client/lib/request_handlers_scene.js`
+- `client/lib/request_handlers_essential.js`
+- `client/lib/request_handlers_timeline.js`
+- `client/lib/request_handlers_layer_structure.js`
+- `client/lib/request_handlers.js`
+- `client/lib/server.js`

package/examples/scene.example.json

@@ -0,0 +1,46 @@
+{
+  "composition": {
+    "name": "Main",
+    "width": 1920,
+    "height": 1080,
+    "duration": 8,
+    "frameRate": 30,
+    "pixelAspect": 1,
+    "createIfMissing": true,
+    "setActive": true
+  },
+  "layers": [
+    {
+      "id": "bg",
+      "type": "solid",
+      "name": "BG",
+      "width": 1920,
+      "height": 1080,
+      "color": [18, 34, 56],
+      "timing": {
+        "inPoint": 0,
+        "outPoint": 8
+      }
+    },
+    {
+      "id": "title",
+      "type": "text",
+      "name": "Title",
+      "text": "Hello Agent",
+      "transform": {
+        "position": [960, 540],
+        "scale": [100, 100],
+        "opacity": 100
+      },
+      "animations": [
+        {
+          "propertyPath": "ADBE Transform Group.ADBE Position",
+          "keyframes": [
+            { "time": 0, "value": [960, 760], "outInterp": "bezier", "easeOut": [0, 70] },
+            { "time": 0.8, "value": [960, 540], "inInterp": "bezier", "easeIn": [0, 80] }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ae-agent-skills",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "One-command installer for the ae-agent-skill After Effects extension and CLI.",
   "type": "module",
   "bin": {
@@ -10,6 +10,9 @@
   "files": [
     "bin",
     "templates",
+    "schemas",
+    "examples",
+    "docs",
     "scripts/signing",
     "CSXS",
     "client",

package/schemas/scene.schema.json

@@ -0,0 +1,454 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/ae-agent-skills/scene.schema.json",
+  "title": "AE Declarative Scene",
+  "type": "object",
+  "required": [
+    "layers"
+  ],
+  "properties": {
+    "composition": {
+      "$ref": "#/$defs/composition"
+    },
+    "layers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/layer"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "numberArray2": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "items": {
+        "type": "number"
+      }
+    },
+    "numberArray3": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "items": {
+        "type": "number"
+      }
+    },
+    "numberArray2or3": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/numberArray2"
+        },
+        {
+          "$ref": "#/$defs/numberArray3"
+        }
+      ]
+    },
+    "composition": {
+      "type": "object",
+      "properties": {
+        "compId": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "compName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "width": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "height": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "duration": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "frameRate": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "pixelAspect": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "createIfMissing": {
+          "type": "boolean"
+        },
+        "setActive": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "timing": {
+      "type": "object",
+      "properties": {
+        "inPoint": {
+          "type": "number"
+        },
+        "outPoint": {
+          "type": "number"
+        },
+        "startTime": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "transform": {
+      "type": "object",
+      "properties": {
+        "anchorPoint": {
+          "$ref": "#/$defs/numberArray2or3"
+        },
+        "position": {
+          "$ref": "#/$defs/numberArray2or3"
+        },
+        "scale": {
+          "$ref": "#/$defs/numberArray2or3"
+        },
+        "rotation": {
+          "type": "number"
+        },
+        "opacity": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "propertyValue": {
+      "type": "object",
+      "required": [
+        "propertyPath",
+        "value"
+      ],
+      "properties": {
+        "propertyPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {}
+      },
+      "additionalProperties": false
+    },
+    "effectParam": {
+      "type": "object",
+      "required": [
+        "value"
+      ],
+      "properties": {
+        "propertyPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "matchName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "propertyIndex": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "value": {}
+      },
+      "oneOf": [
+        {
+          "required": [
+            "propertyPath"
+          ]
+        },
+        {
+          "required": [
+            "matchName"
+          ]
+        },
+        {
+          "required": [
+            "propertyIndex"
+          ]
+        }
+      ],
+      "additionalProperties": false
+    },
+    "effect": {
+      "type": "object",
+      "required": [
+        "matchName"
+      ],
+      "properties": {
+        "matchName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "params": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/effectParam"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "keyframe": {
+      "type": "object",
+      "required": [
+        "time",
+        "value"
+      ],
+      "properties": {
+        "time": {
+          "type": "number"
+        },
+        "value": {},
+        "inInterp": {
+          "type": "string",
+          "enum": [
+            "linear",
+            "bezier",
+            "hold"
+          ]
+        },
+        "outInterp": {
+          "type": "string",
+          "enum": [
+            "linear",
+            "bezier",
+            "hold"
+          ]
+        },
+        "easeIn": {},
+        "easeOut": {}
+      },
+      "additionalProperties": false
+    },
+    "animation": {
+      "type": "object",
+      "required": [
+        "propertyPath",
+        "keyframes"
+      ],
+      "properties": {
+        "propertyPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "keyframes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/keyframe"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "expressionBinding": {
+      "type": "object",
+      "required": [
+        "propertyPath",
+        "expression"
+      ],
+      "properties": {
+        "propertyPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "expression": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "essentialProperty": {
+      "type": "object",
+      "required": [
+        "propertyPath"
+      ],
+      "properties": {
+        "propertyPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "essentialName": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "repeater": {
+      "type": "object",
+      "properties": {
+        "groupIndex": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "copies": {
+          "type": "number"
+        },
+        "offset": {
+          "type": "number"
+        },
+        "position": {
+          "$ref": "#/$defs/numberArray2"
+        },
+        "scale": {
+          "$ref": "#/$defs/numberArray2"
+        },
+        "rotation": {
+          "type": "number"
+        },
+        "startOpacity": {
+          "type": "number"
+        },
+        "endOpacity": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "layer": {
+      "type": "object",
+      "required": [
+        "id",
+        "type"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "text",
+            "null",
+            "solid",
+            "shape"
+          ]
+        },
+        "name": {
+          "type": "string"
+        },
+        "parentId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "text": {
+          "type": "string"
+        },
+        "width": {
+          "type": "number"
+        },
+        "height": {
+          "type": "number"
+        },
+        "color": {
+          "$ref": "#/$defs/numberArray3"
+        },
+        "duration": {
+          "type": "number"
+        },
+        "shapeType": {
+          "type": "string",
+          "enum": [
+            "ellipse",
+            "rect"
+          ]
+        },
+        "shapeSize": {
+          "$ref": "#/$defs/numberArray2"
+        },
+        "shapePosition": {
+          "$ref": "#/$defs/numberArray2"
+        },
+        "shapeFillColor": {
+          "$ref": "#/$defs/numberArray3"
+        },
+        "shapeFillOpacity": {
+          "type": "number"
+        },
+        "shapeStrokeColor": {
+          "$ref": "#/$defs/numberArray3"
+        },
+        "shapeStrokeOpacity": {
+          "type": "number"
+        },
+        "shapeStrokeWidth": {
+          "type": "number"
+        },
+        "shapeStrokeLineCap": {
+          "type": "string",
+          "enum": [
+            "butt",
+            "round",
+            "projecting"
+          ]
+        },
+        "shapeRoundness": {
+          "type": "number"
+        },
+        "timing": {
+          "$ref": "#/$defs/timing"
+        },
+        "transform": {
+          "$ref": "#/$defs/transform"
+        },
+        "propertyValues": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/propertyValue"
+          }
+        },
+        "effects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/effect"
+          }
+        },
+        "animations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/animation"
+          }
+        },
+        "expressions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/expressionBinding"
+          }
+        },
+        "essentialProperties": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/essentialProperty"
+          }
+        },
+        "repeaters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/repeater"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/templates/skills/aftereffects-cli.SKILL.md

@@ -33,6 +33,13 @@ description: Command-by-command After Effects editing via ae-cli. Best for surgi
 3. 必要な更新コマンドを最小回数で実行
 4. 変更後に `layers` / `properties` で結果確認
 
+## 参照ファイル（固定）
+
+- schema: `~/ae-agent-skills/scene.schema.json`
+- サンプル: `~/ae-agent-skills/references/scene.example.json`
+- CLIリファレンス（日本語）: `~/ae-agent-skills/references/cli.ja.md`
+- CLIリファレンス（英語）: `~/ae-agent-skills/references/cli.md`
+
 ## 宣言型へ切り替える目安
 
 - 同種の変更を複数レイヤーへ繰り返す
@@ -83,4 +90,4 @@ ae-cli layers
 - 既存シーンへの単発・部分修正は命令型の方が安全な場合が多い（影響範囲を局所化しやすい）。
 - 同じ処理を複数コマンドで繰り返す必要がある場合は、宣言型 `apply-scene` へ切り替える。
 - expression の不調は `ae-cli expression-errors` で確認する。
-- scene JSON を一時的に作る場合は `work/`（作業中）と `done/`（完了保管）を使い、どちらもコミットしない。
+- scene JSON を一時的に作る場合は `~/ae-agent-skills/work/`（作業中）と `~/ae-agent-skills/done/`（完了保管）を使う。

package/templates/skills/aftereffects-declarative.SKILL.md

@@ -30,20 +30,27 @@ After Effects を宣言型 JSON で構築する標準スキル。
 ## 基本フロー
 
 1. 疎通確認: `ae-cli health`
-2. scene JSON を作成/更新（作業中は `work/` 配下）
-3. `--validate-only` で検証
-4. 実適用
-5. `layers` / `properties` / `expression-errors` で確認
-6. 完了版は `done/` 配下へコピーして保管
+2. `~/ae-agent-skills/scene.schema.json` と `~/ae-agent-skills/references/scene.example.json` を確認
+3. scene JSON を作成/更新（作業中は `~/ae-agent-skills/work/` 配下）
+4. `--validate-only` で検証
+5. 実適用
+6. `layers` / `properties` / `expression-errors` で確認
+7. 完了版は `~/ae-agent-skills/done/` 配下へコピーして保管
+
+## 参照ファイル（固定）
+
+- schema: `~/ae-agent-skills/scene.schema.json`
+- サンプル: `~/ae-agent-skills/references/scene.example.json`
+- CLIリファレンス（日本語）: `~/ae-agent-skills/references/cli.ja.md`
+- CLIリファレンス（英語）: `~/ae-agent-skills/references/cli.md`
 
 ## ファイル運用ルール（重要）
 
-- `work/`: 作業中の scene JSON を置くディレクトリ
-- `done/`: 完了した scene JSON の保管ディレクトリ
-- どちらもリポジトリにはコミットしない（`.gitignore` 前提）
+- `~/ae-agent-skills/work/`: 作業中の scene JSON を置くディレクトリ
+- `~/ae-agent-skills/done/`: 完了した scene JSON の保管ディレクトリ
 - 例:
-  - `ae-cli apply-scene --scene-file work/main.scene.json --validate-only`
-  - `ae-cli apply-scene --scene-file work/main.scene.json`
+  - `ae-cli apply-scene --scene-file ~/ae-agent-skills/work/main.scene.json --validate-only`
+  - `ae-cli apply-scene --scene-file ~/ae-agent-skills/work/main.scene.json`
 
 ## コマンド
 
@@ -68,6 +75,7 @@ ae-cli expression-errors
 
 - `layers[].id` は必須推奨（upsert の安定キー）
 - `layers[].parentId` は scene id を参照
+- 推測でキーを作らず、必ず `~/ae-agent-skills/scene.schema.json` を正として合わせる
 - アニメーション対象プロパティは `animations` で管理
 - 3Dベクトルには2D入力可（`[x,y] -> [x,y,0]` 自動補完）
 - Repeater は `layers[].repeaters[]`
@@ -78,7 +86,7 @@ ae-cli expression-errors
 
 ## 最小テンプレート（このまま使える）
 
-以下を `work/min.scene.json` として保存して、そのまま `validate/apply` できる。
+以下を `~/ae-agent-skills/work/min.scene.json` として保存して、そのまま `validate/apply` できる。
 
 ```json
 {
@@ -108,8 +116,8 @@ ae-cli expression-errors
 ```
 
 ```bash
-ae-cli apply-scene --scene-file work/min.scene.json --validate-only
-ae-cli apply-scene --scene-file work/min.scene.json
+ae-cli apply-scene --scene-file ~/ae-agent-skills/work/min.scene.json --validate-only
+ae-cli apply-scene --scene-file ~/ae-agent-skills/work/min.scene.json
 ```
 
 ## propertyPath 運用ルール（汎用）