after-effects

## Overview This skill automates After Effects by generating ExtendScript (.jsx) and executing it via osascript. It reads project state through query scripts, uses rule files for domain knowledge, and wraps all mutations in undo groups. ## First-Time Setup 1. Run `scripts/runner.sh` with any query script to detect the AE version 2. If multiple AE versions are installed, the user must choose one — runner.sh will prompt 3. Ensure AE Preferences > Scripting & Expressions > "Allow Scripts to Write Files and Access Network" is enabled ## Workflow For every user request: ### Step 1: Gather context (auto-run, no confirmation needed) Use `--background` for all query scripts — this skips `ae.activate()` so AE doesn't steal focus: ```bash bash scripts/runner.sh --background scripts/active-state.jsx ``` Then read `/tmp/ae-assistant-result.json` for active comp, selected layers, CTI. If this is the first interaction or the project context is unknown, also run: ```bash bash scripts/runner.sh --background scripts/project-overview.jsx ``` This returns a **summary** by default: folder tree with counts, all comps listed, footage grouped by file type. NOT every individual file. To drill into a specific folder: ```bash bash scripts/runner.sh --background scripts/project-overview.jsx '{"mode": "folder", "folderName": "Images"}' ``` Only use full mode when you actually need every item listed: ```bash bash scripts/runner.sh --background scripts/project-overview.jsx '{"mode": "full"}' ``` ### Step 2: Drill down if needed (auto-run) If the task targets a specific comp: ```bash bash scripts/runner.sh --background scripts/comp-detail.jsx '{"compName": "Comp Name"}' ``` If the task targets specific layers: ```bash bash scripts/runner.sh --background scripts/layer-detail.jsx '{"layerNames": ["Layer 1", "Layer 2"]}' ``` Omit `compName` to use the active comp. Omit `layerNames` to use selected layers. #### Additional query scripts **Expression errors** — scan for broken expressions: ```bash bash scripts/runner.sh --background scripts/expression-errors.jsx bash scripts/runner.sh --background scripts/expression-errors.jsx '{"compName": "Main Comp"}' ``` **Font inventory** — list all fonts used across the project: ```bash bash scripts/runner.sh --background scripts/font-inventory.jsx ``` **Project audit** — comprehensive health check (unused footage, missing files, expression errors, duplicate solids, font issues, empty folders): ```bash bash scripts/runner.sh --background scripts/project-audit.jsx bash scripts/runner.sh --background scripts/project-audit.jsx '{"checks": ["unused", "missing", "expressions"]}' ``` ### Step 3: Load domain knowledge Read the relevant rule file from `rules/`. Always read `rules/extendscript-fundamentals.md` — it contains ES3 constraints that apply to every generated script. | Task involves | Load rule file | |---|---| | Layers (create, move, parent, duplicate) | [rules/layer-manipulation.md](rules/layer-manipulation.md) | | Keyframes, animation, easing | [rules/keyframes-animation.md](rules/keyframes-animation.md) | | Expressions | [rules/expressions.md](rules/expressions.md) | | Compositions (create, precompose, nest) | [rules/composition-management.md](rules/composition-management.md) | | Effects and parameters | [rules/effects.md](rules/effects.md) | | Import, footage, assets | [rules/assets-footage.md](rules/assets-footage.md) | | Render queue, export | [rules/rendering.md](rules/rendering.md) | | Bulk/batch operations | [rules/batch-operations.md](rules/batch-operations.md) | | Version-specific features | [references/ae-api-versions.md](references/ae-api-versions.md) | ### Step 4: Generate the action script **CRITICAL: Resolve the skill's real path first** Before writing or executing any action script, resolve the skill's real (non-symlinked) path. ExtendScript `#include` cannot follow symlinks, so you MUST use the real filesystem path. Run this once at the start of each session: ```bash SKILL_SCRIPTS="$(readlink -f ~/.claude/skills/after-effects-assistant/scripts 2>/dev/null || readlink ~/.claude/skills/after-effects-assistant/scripts)" echo "$SKILL_SCRIPTS" ``` Use the resolved path (`$SKILL_SCRIPTS`) for all subsequent Write and Bash commands in this session. **Why this matters:** - `~/.claude/skills/` is typically a symlink — ExtendScript `#include` fails through symlinks - Writing to the real `scripts/` directory lets `#include "lib/json2.jsx"` resolve correctly - The resolved path changes per machine, so never hardcode it Every generated script MUST follow this template: ```jsx #include "lib/json2.jsx" #include "lib/utils.jsx" (function() { app.beginUndoGroup("AE Assistant: <action description>"); try { var args = readArgs(); var comp = getActiveComp(); if (!comp) return; // ... action code ... writeResult({ success: true, message: "<what was done>" }); } catch (e) { try { writeResult({ error: e.toString(), line: e.line, fileName: e.fileName }); } catch(e2) { writeError(e.toString(), "line:" + e.line); } } finally { app.endUndoGroup(); } })(); ``` #### utils.jsx helpers available for generated scripts | Function | Purpose | |----------|---------| | `writeResult(obj)` | Write JSON result to `/tmp/ae-assistant-result.json` | | `writeError(msg, detail)` | Last-resort error capture when JSON.stringify fails | | `readArgs()` | Read args from `/tmp/ae-assistant-args.json` | | `getLayerType(layer)` | Returns type string: "shape", "text", "null", "precomp", etc. | | `getBlendModeName(mode)` | BlendingMode enum → string name | | `getActiveComp()` | Returns active comp or writes error and returns null | | `getSelectedOrAllLayers(comp)` | Selected layers array, or all layers if none selected | | `hexToRGB(hex)` | `"#ff0000"` → `[1, 0, 0]` | | `getCompByName(name)` | Find comp in project items by name | | `walkProperties(group, leafFn, path)` | Recursive property tree walker — calls `leafFn(prop, path)` on leaves | | `bubbleSort(arr, compareFn)` | ES3-compatible in-place sort | | `framesToSeconds(frames, comp)` | Frame count → seconds via `comp.frameDuration` | | `appendLog(message)` | Append to `~/.ae-assistant-extendscript.log` | **Write the script using the Write tool, then execute with a short bash command:** 1. Use the **Write** tool to write the script to `$SKILL_SCRIPTS/ae-action.jsx` (the resolved real path) 2. Execute it with bash: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/ae-action.jsx" ``` **IMPORTANT:** Do NOT use `cat > file << 'SCRIPT'` heredocs — they put the entire script in the bash command, cluttering the permission prompt. Always use the Write tool for the script content, then a short bash command to run it. ### Step 5: Execute or confirm **Auto-run** (no confirmation needed): - All read-only queries (active-state, project-overview, comp-detail, layer-detail, expression-errors, font-inventory, project-audit) - Non-destructive additions: adding a keyframe, adding an effect, creating a layer, creating a comp **Confirm before running** (show the script and ask the user): - Deleting layers or comps - Removing keyframes - Replacing footage - Clearing expressions - Render queue operations - Project cleanup (removing unused items, consolidating solids) - Any operation the user might not expect ### Built-in action scripts Before generating a custom `ae-action.jsx`, check if a built-in script already handles the task. These are permanent, tested scripts with args-based behavior: **True Comp Duplicator** — deep-clone a comp with independent sub-comps (confirm before running): ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/true-comp-duplicator.jsx" '{"compName": "Main Comp", "suffix": " COPY"}' ``` **Font Replace** — find and replace fonts across the project. Always dryRun first: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/font-replace.jsx" '{"find": "Helvetica", "replace": "Inter-Regular", "dryRun": true}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/font-replace.jsx" '{"find": "Helvetica", "replace": "Inter-Regular"}' ``` **Project Cleanup** — remove unused footage, consolidate duplicate solids, remove empty folders. Always dryRun first: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/project-cleanup.jsx" '{"dryRun": true}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/project-cleanup.jsx" ``` **Batch Rename** — rename layers, comps, or project items in bulk: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/batch-rename.jsx" '{"target": "layers", "mode": "find-replace", "find": "Layer", "replace": "Element"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/batch-rename.jsx" '{"target": "layers", "mode": "prefix", "prefix": "BG_"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/batch-rename.jsx" '{"target": "layers", "mode": "sequence", "base": "Card", "start": 1}' ``` **Layer Stagger** — offset selected layers in time for cascade animations: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/layer-stagger.jsx" '{"offset": 0.1, "unit": "seconds", "direction": "forward"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/layer-stagger.jsx" '{"offset": 2, "unit": "frames"}' ``` **Expression Replace** — find/replace text in expressions project-wide. Always dryRun first: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/expression-replace.jsx" '{"find": "comp(\"Old\")", "replace": "comp(\"New\")", "dryRun": true}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/expression-replace.jsx" '{"find": "comp(\"Old\")", "replace": "comp(\"New\")"}' ``` **Organize Project** — auto-sort project panel items into folders by type: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/organize-project.jsx" '{"structure": "by-type"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/organize-project.jsx" '{"structure": "by-extension"}' ``` **Batch Comp Settings** — change fps, resolution, duration across multiple comps: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/batch-comp-settings.jsx" '{"scope": "all", "fps": 25}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/batch-comp-settings.jsx" '{"compNames": ["Comp 1", "Comp 2"], "width": 3840, "height": 2160}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/batch-comp-settings.jsx" '{"scope": "nested", "fps": 30, "duration": 10}' ``` **Easing Presets** — apply professional easing or bounce/elastic expressions: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/easing-presets.jsx" '{"preset": "smooth"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/easing-presets.jsx" '{"preset": "snappy"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/easing-presets.jsx" '{"preset": "bounce"}' ``` **Anchor Point Mover** — reposition anchor point with visual position compensation: ```bash bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/anchor-point-mover.jsx" '{"position": "center"}' bash "$SKILL_SCRIPTS/runner.sh" "$SKILL_SCRIPTS/anchor-point-mover.jsx" '{"position": "bottom-left"}' ``` **Reverse Keyframes** — reverse animation on selected properties: