@skilly-hand/skilly-hand 0.26.0 → 0.26.2

package/CHANGELOG.md

@@ -16,6 +16,39 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.26.2] - 2026-05-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.2)
+
+### Added
+- Added portable `motion-animation` skill with official Motion guidance for JavaScript, React components, gestures, scroll animation, layout animation, exit animation, performance, accessibility, and source verification.
+
+### Changed
+- Updated `frontend-design` to route Motion-native animation work through `motion-animation` alongside existing GSAP routing.
+- Updated catalog and install expectations so Motion guidance is included in generated skill lists and frontend-design dependencies.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.26.1] - 2026-05-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.1)
+
+### Added
+- Added portable `gsap-animation` skill with official-source GSAP guidance for timelines, ScrollTrigger, React `useGSAP`, plugin selection, performance, cleanup, and reduced-motion patterns.
+- Added GSAP project detection so installs recommend `gsap-animation` when `gsap` or `@gsap/react` is present.
+
+### Changed
+- Updated `frontend-design` to route advanced motion work through `gsap-animation` and include the new critique workflow in catalog metadata.
+- Updated selected skill installation to include portable skill dependencies automatically.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.26.0] - 2026-05-01
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.0)
 

package/README.md

@@ -75,6 +75,8 @@ The catalog currently includes:
 - `angular-guidelines`
 - `figma-mcp-0to1`
 - `frontend-design`
+- `gsap-animation`
+- `motion-animation`
 - `output-optimizer`
 - `project-security`
 - `project-teacher`

package/catalog/README.md

@@ -8,7 +8,9 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
 | `angular-guidelines` | Guide Angular code generation, review, and performance tuning using latest stable Angular verification, official Angular skill guidance, and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
-| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases. | frontend, design, workflow, ui, motion, greenfield | all |
+| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish. | frontend, design, workflow, ui, motion, greenfield | all |
+| `gsap-animation` | Guide GSAP animation implementation using only official GSAP documentation and the official greensock/gsap-skills source material. Trigger: implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation. | frontend, animation, motion, gsap, workflow | all |
+| `motion-animation` | Guide Motion, formerly Framer Motion, animation implementation using only official Motion documentation. Trigger: implementing, reviewing, or choosing Motion for JavaScript animation, React motion components, gestures, scroll animation, layout animation, exit animation, or framework-agnostic UI motion. | frontend, animation, motion, framer-motion, workflow | all |
 | `output-optimizer` | Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness. | core, workflow, efficiency, communication | all |
 | `project-security` | Scan project configuration and release surfaces for leak and security risks, and enforce security gates on commit, push, and publish workflows across GitHub, GitLab, npm, pnpm, yarn, and generic CI. Trigger: validating repository security posture, preventing secret leaks, or hardening delivery pipelines. | security, workflow, quality, core | all |
 | `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |

package/catalog/catalog-index.json

@@ -4,6 +4,8 @@
   "angular-guidelines",
   "figma-mcp-0to1",
   "frontend-design",
+  "gsap-animation",
+  "motion-animation",
   "output-optimizer",
   "project-security",
   "project-teacher",

package/catalog/skills/frontend-design/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "frontend-design"
-description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases."
+description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-05"
+  last-edit: "2026-05-03"
   license: "Apache-2.0"
-  version: "1.1.0"
-  changelog: "v1.1.0: Added design-context-setter agent for greenfield/DESIGN.md workflow; added visual-refiner agent for post-generation quality evaluation; added motion-designer agent for stack-aware micro-interactions; added aesthetic-archetypes reference asset; expanded SKILL.md routing map with optional motion and refinement phases; upgraded component-designer with interaction states checklist and aesthetic principles"
-  auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
+  version: "1.4.0"
+  changelog: "Added Motion-aware routing through motion-animation alongside gsap-animation; improves animation handoffs for Motion-native JavaScript and React projects; affects frontend-design motion sequencing, metadata, and catalog dependencies"
+  auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
   allowed-tools:
     - "Read"
     - "Grep"
@@ -15,6 +15,8 @@ skillMetadata:
     - "Bash"
     - "Edit"
     - "Write"
+    - "Task"
+    - "SubAgent"
 ---
 # Frontend Design Guide
 
@@ -45,8 +47,9 @@ Always run stack detection first. Never skip to design.
 | 0 (always first) | Detect framework, UI library, CSS approach, tokens, and existing patterns | [agents/stack-detector.md](agents/stack-detector.md) |
 | 0b (if no DESIGN.md and no existing components) | Gather design intent and create DESIGN.md | [agents/design-context-setter.md](agents/design-context-setter.md) |
 | 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
-| 2 (optional) | Add motion and micro-interactions | [agents/motion-designer.md](agents/motion-designer.md) |
-| 3 (optional) | Evaluate quality and refine the output | [agents/visual-refiner.md](agents/visual-refiner.md) |
+| 2 (mandatory after generation) | Challenge the output for AI slop, weak hierarchy, heuristic failures, and unclear product fit | [agents/critique.md](agents/critique.md) |
+| 3 (after critique) | Apply visual quality refinements routed by critique | [agents/visual-refiner.md](agents/visual-refiner.md) |
+| 4 (optional) | Add motion and micro-interactions, routing Motion-native and GSAP-native work to the matching official-source skill | [agents/motion-designer.md](agents/motion-designer.md) |
 
 ---
 
@@ -58,8 +61,9 @@ Always run stack detection first. Never skip to design.
 4. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
 5. **Scan existing tokens and components** — read what already exists before proposing anything.
 6. **Design with confirmed context only** — hand off to `component-designer` only after steps 2–4 are complete.
-7. **Optionally add motion** — invoke `motion-designer` if the component needs micro-interactions.
-8. **Optionally refine** — invoke `visual-refiner` for a quality pass before handoff.
+7. **Critique after generation** — invoke `critique` for a frontend-only challenge pass before polish.
+8. **Refine from critique** — invoke `visual-refiner` for visual fixes routed by critique.
+9. **Optionally add motion** — invoke `motion-designer` if critique, refinement, or the user identifies a motion need. Route Motion-native JavaScript/React animation through `motion-animation`; route GSAP timelines, ScrollTrigger, and plugin decisions through `gsap-animation`.
 
 ---
 
@@ -190,8 +194,14 @@ Ready to implement?
   YES -> Hand off to component-designer with full confirmed context
 
 After generation:
+  -> Invoke critique to challenge design quality and route fixes
+  -> Invoke visual-refiner for critique-routed visual fixes
   -> Does the component need motion? -> Invoke motion-designer
-  -> Does the output need a quality pass? -> Invoke visual-refiner
+       -> Does motion match existing Motion/Framer Motion, React motion props, layout, exit, gestures, or lightweight JS animation?
+            YES -> Use motion-animation for official-source Motion guidance
+       -> Does motion need GSAP timelines, ScrollTrigger, pin/scrub behavior, or GSAP plugins?
+            YES -> Use gsap-animation for official-source GSAP guidance
+            NO  -> Use confirmed stack primitives
 ```
 
 ---
@@ -275,7 +285,8 @@ find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
 - Stack detection procedure: [agents/stack-detector.md](agents/stack-detector.md)
 - Design context setup (greenfield): [agents/design-context-setter.md](agents/design-context-setter.md)
 - Component design rules: [agents/component-designer.md](agents/component-designer.md)
-- Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.md)
+- Frontend design critique: [agents/critique.md](agents/critique.md)
 - Visual quality refinement: [agents/visual-refiner.md](agents/visual-refiner.md)
+- Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.md)
 - Full scan checklist: [assets/stack-scan-checklist.md](assets/stack-scan-checklist.md)
 - Aesthetic archetypes reference: [assets/aesthetic-archetypes.md](assets/aesthetic-archetypes.md)

package/catalog/skills/frontend-design/agents/critique.md

@@ -0,0 +1,190 @@
+# Critique
+
+## Precondition
+
+**Run only after `component-designer` has produced or proposed a concrete UI.**
+
+This agent is the frontend-design challenge gate. It acts like a frontend-only roaster: direct, skeptical, and useful. Its job is to decide whether the design feels intentional or like generic AI output before `visual-refiner` applies polish.
+
+Before critiquing:
+
+1. Confirm stack detection has completed and the user accepted the stack summary.
+2. Read `DESIGN.md` if it exists.
+3. Inspect the generated/proposed UI source and, when available, the rendered page.
+4. Compare against sampled project components, tokens, and interaction patterns.
+
+Do not use this agent when:
+
+- No concrete UI exists yet.
+- The request is only stack discovery or design brief creation.
+- The user explicitly asks to skip critique.
+
+---
+
+## Critique Principles
+
+- Challenge the design, not the user.
+- Name the strongest weakness first.
+- Prefer evidence from the codebase, `DESIGN.md`, or rendered UI over taste alone.
+- Keep the roast constructive: a sharp sentence that exposes the gap, followed by a fix path.
+- Do not apply changes in this agent. Route fixes to the right follow-up agent or skill.
+
+---
+
+## Evaluation Protocol
+
+Run all six passes. Do not skip a pass because the UI "mostly works."
+
+### Pass 1 - Anti-Slop Detection
+
+Flag visible tells of generic AI design. Use project evidence to decide whether a pattern is intentional or sloppy.
+
+| Area | Patterns to Challenge |
+| --- | --- |
+| Visual details | Glassmorphism everywhere, generic rounded rectangles with shadows, thick side accent borders, decorative tiny charts, unexplained glow effects |
+| Typography | Flat type hierarchy, overused default fonts, single font for every role, monospace as "technical" shorthand, all-caps body text |
+| Color and contrast | Purple/violet gradients by reflex, neon-on-dark by reflex, gradient text, pure black or pure white, gray text on colored backgrounds, low contrast |
+| Layout and space | Everything centered, hero metric blocks by default, identical card grids, monotonous spacing, nested cards, wrapping every section in cards, long line length |
+| Motion | Bounce/elastic easing, motion without state meaning, animated layout properties |
+| Interaction | Every button styled as primary, hidden actions, redundant labels, missing focus/disabled/loading states |
+| Responsive | Critical features hidden on mobile, touch targets too small, desktop layout merely squeezed |
+| General quality | Cramped padding, skipped heading levels, tiny body text, tight line height, wide tracking on body text, justified screen text |
+
+For each finding, include:
+
+- `what`: the pattern.
+- `why`: why it weakens this specific interface.
+- `fix`: the project-derived correction or the agent that should handle it.
+
+### Pass 2 - Design Intent Fit
+
+Check whether the UI serves the actual product context.
+
+- Audience: Does the visual language match who uses it?
+- Job: Does the layout prioritize the user's real task?
+- Brand: Does it follow `DESIGN.md` personality and anti-references?
+- Mode: Is this a brand surface where design is the product, or a product surface where design serves repeated use?
+- Distinction: Would this still be recognizable if the logo and copy were removed?
+
+### Pass 3 - Nielsen Heuristics
+
+Score only what can be judged from the current UI. Use `0` to `4`.
+
+| Heuristic | Score Meaning |
+| --- | --- |
+| Visibility of status | Loading, progress, saved, empty, and error states are clear |
+| Match with real world | Labels, groupings, and controls use language the audience recognizes |
+| User control | Escape, undo, cancel, back, and destructive action safety are available where needed |
+| Consistency and standards | Component patterns match the project and platform expectations |
+| Error prevention | The UI prevents likely mistakes before they happen |
+| Recognition over recall | Available actions and context are visible without guessing |
+| Flexibility and efficiency | Frequent users are not slowed by decorative friction |
+| Aesthetic and minimalist design | Every visible element earns its place |
+
+### Pass 4 - Cognitive Load
+
+Count failures. A good interface reduces decisions, not just pixels.
+
+- Too many equally weighted actions.
+- Too many containers or borders.
+- Too many text styles.
+- Repeated explanatory copy.
+- Competing focal points.
+- Unclear next action.
+- Dense controls without grouping.
+- Decorative elements that look interactive.
+
+### Pass 5 - Persona Pressure Tests
+
+Use three personas unless `DESIGN.md` defines better ones:
+
+- `The new user`: understands the first meaningful action in under five seconds.
+- `The returning user`: can complete the repeated task quickly without rereading the page.
+- `The skeptic`: has seen generic AI/SaaS layouts and needs proof this is specific.
+
+Score each `0` to `4` and name the failure if the score is below `3`.
+
+### Pass 6 - Route the Fixes
+
+Every priority issue must name the next tool to use:
+
+| Issue Type | Route To |
+| --- | --- |
+| Visual hierarchy, spacing, color, typography, card depth | `visual-refiner` |
+| Missing or excessive motion, easing, reduced-motion coverage | `motion-designer` |
+| Component API, structure, state model, or markup contract | `component-designer` |
+| Missing product/design intent or unresolved brand direction | `design-context-setter` |
+| Accessibility, semantics, keyboard, contrast, screen-reader behavior | `accessibility-audit` |
+| Security-sensitive UI flows, release gates, unsafe forms | `project-security` |
+| Test coverage for states, responsiveness, or interaction behavior | stack-specific tester or `test-driven-development` |
+
+If a fix needs another sub-agent or skill, call that out explicitly. Do not silently merge responsibilities.
+
+When the user or host workflow asks to continue after critique, invoke the routed agent that matches the highest-priority fix. Use one follow-up agent at a time so ownership stays clear. Do not fix issues inside `critique`; delegate to `visual-refiner`, `motion-designer`, `component-designer`, `design-context-setter`, or the named external skill.
+
+---
+
+## Output Format
+
+Use this compact report:
+
+```text
+FRONTEND DESIGN CRITIQUE
+------------------------
+Verdict: [pass / watch / fail] - [strongest reason]
+Roast: [one constructive jab at the weakest design decision]
+
+Scores:
+- Anti-slop: [0-4] ([specific tells])
+- Heuristics: [0-4 average] ([lowest heuristic])
+- Cognitive load: [N/8 failures]
+- Persona fit: [0-4 average] ([weakest persona])
+
+Priority Fixes:
+1. [what] - [why] - Fix: [specific change] - Use next: [agent/skill]
+2. [what] - [why] - Fix: [specific change] - Use next: [agent/skill]
+3. [what] - [why] - Fix: [specific change] - Use next: [agent/skill]
+
+Questions:
+- [only questions the interface cannot answer from project context]
+```
+
+Keep priority fixes to three to five items. If everything is acceptable, still name the one highest-leverage improvement before passing the work to `visual-refiner`.
+
+---
+
+## Severity Rules
+
+Use these verdicts:
+
+| Verdict | Meaning |
+| --- | --- |
+| `pass` | No slop tells or blockers; only minor polish remains |
+| `watch` | Direction is viable, but one or two design decisions need correction |
+| `fail` | The UI reads as generic, incoherent, inaccessible, or mismatched to product intent |
+
+Raise severity when:
+
+- The same slop pattern appears in multiple sections.
+- The issue affects comprehension, conversion, task completion, or accessibility.
+- The design contradicts `DESIGN.md` or sampled project components.
+- The UI hides critical function on mobile.
+
+Lower severity when:
+
+- The pattern is established elsewhere in the project and works for the audience.
+- The issue is isolated and easy for `visual-refiner` to correct.
+- The user explicitly requested the aesthetic and it does not harm usability.
+
+---
+
+## Finished Work
+
+This agent is done when it has:
+
+- Given a verdict.
+- Named the weakest design decision.
+- Scored anti-slop, heuristics, cognitive load, and persona fit.
+- Listed three to five prioritized fixes.
+- Routed each fix to the exact next agent or skill.
+- Asked only unresolved product/design questions.

package/catalog/skills/frontend-design/agents/motion-designer.md

@@ -6,6 +6,10 @@
 
 Motion must be implemented using the animation primitives already available in the project's stack. Never introduce a new animation library without the user's explicit approval.
 
+For Motion-native animation needs, prefer a handoff to `motion-animation` when Motion or Framer Motion is already installed, explicitly requested, or approved as a new dependency. Use that skill for framework-agnostic JavaScript Motion APIs, React `motion` components, gestures, scroll-linked animation, scroll-triggered animation, layout animation, and exit animation.
+
+For GSAP-native animation needs, prefer a handoff to `gsap-animation` when GSAP is already installed, explicitly requested, or approved as a new dependency. Use that skill for GSAP timelines, ScrollTrigger pin/scrub behavior, and GSAP plugin decisions.
+
 ---
 
 ## When to Use
@@ -40,7 +44,7 @@ grep -rn "transition" src/ --include="*.css" --include="*.scss" --include="*.mod
 grep -rn "@keyframes" src/ --include="*.css" --include="*.scss" | head -5
 
 # Check for Tailwind animation utilities
-grep -n "transition\|duration\|ease\|animate-" src/ --include="*.tsx" --include="*.vue" | head -10
+grep -rn "transition\|duration\|ease\|animate-" src/ --include="*.tsx" --include="*.vue" | head -10
 ```
 
 Report what was found:
@@ -54,6 +58,10 @@ Animation stack:
 
 If no animation primitives are found, ask: "This project has no existing animation setup. Should I use CSS transitions only (no new dependencies), or would you like to add a library? If so, which one?"
 
+If Motion or Framer Motion is already established, or the user asks for Motion, React motion props, gestures, layout animation, exit animation, lightweight framework-agnostic JavaScript animation, `whileInView`, or `useScroll`, invoke `motion-animation`. If `motion` is not already installed, ask for approval before adding it.
+
+If the motion needs GSAP timeline sequencing, ScrollTrigger pinning/scrub, GSAP plugins, or explicit GSAP behavior, invoke `gsap-animation`. If `gsap` is not already installed, ask for approval before adding it. If another animation library is already established and the user did not ask to switch, respect the existing library.
+
 ---
 
 ## Opportunity Assessment
@@ -101,6 +109,30 @@ Moments where a small motion adds personality without adding noise:
 
 **Fix**: These are always optional and always ask the user first. Never add delight motion without explicit approval.
 
+### 5. Motion Handoff Opportunities
+
+Some motion work is better handled with official Motion guidance instead of local heuristics:
+
+- The project already uses `motion`, `framer-motion`, or `@motionone/dom`.
+- The user asks for Motion or Framer Motion.
+- React animation should use `motion` components, `AnimatePresence`, `whileHover`, `whileTap`, `whileInView`, `useScroll`, `layout`, or `layoutId`.
+- Framework-agnostic JavaScript animation should use Motion `animate()`, `scroll()`, `inView()`, `hover()`, `press()`, or `stagger()`.
+- The project needs lightweight DOM/SVG/object animation and the user approves Motion as the dependency.
+
+**Fix**: Invoke `motion-animation` and include the detected project stack, dependency status, component scope, requested motion behavior, and reduced-motion expectations. Do not add `motion` without user approval.
+
+### 6. GSAP Handoff Opportunities
+
+Some motion work is better handled with official GSAP guidance instead of local heuristics:
+
+- Multi-step entrance or page choreography that needs timeline sequencing.
+- Scroll reveals, scrubbed animation, pinned sections, or parallax-like effects.
+- Existing GSAP, React `useGSAP()`, Next.js, Vue, Svelte, or Angular animation that needs GSAP lifecycle-safe cleanup.
+- Flip, Draggable, ScrollTrigger, SplitText, SVG, custom easing, or other GSAP plugin decisions.
+- Runtime controls such as pause, play, reverse, seek, progress, or timeScale.
+
+**Fix**: Invoke `gsap-animation` and include the detected project stack, dependency status, component scope, requested motion behavior, and reduced-motion expectations. Do not add `gsap` or `@gsap/react` without user approval.
+
 ---
 
 ## Timing Reference
@@ -176,6 +208,8 @@ If the existing project has no `prefers-reduced-motion` handling anywhere, note
 Before finalizing any motion work:
 
 - [ ] All animation primitives are from the confirmed stack — no new dependencies added without approval.
+- [ ] Motion-suitable work was routed through `motion-animation`.
+- [ ] GSAP-suitable work was routed through `gsap-animation`.
 - [ ] No layout-triggering properties are animated.
 - [ ] All animations have a `prefers-reduced-motion` fallback.
 - [ ] Timing values are within the reference ranges above.

package/catalog/skills/frontend-design/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "frontend-design",
   "title": "Frontend Design",
-  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases.",
+  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish.",
   "portable": true,
   "tags": ["frontend", "design", "workflow", "ui", "motion", "greenfield"],
   "detectors": ["always"],
@@ -10,22 +10,31 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-05",
+    "last-edit": "2026-05-03",
     "license": "Apache-2.0",
-    "version": "1.1.0",
-    "changelog": "v1.1.0: Added design-context-setter agent for greenfield/DESIGN.md workflow; added visual-refiner agent for post-generation quality evaluation; added motion-designer agent for stack-aware micro-interactions; added aesthetic-archetypes reference asset; expanded SKILL.md routing map with optional motion and refinement phases; upgraded component-designer with interaction states checklist and aesthetic principles",
-    "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; adding motion or micro-interactions to existing UI; refining or polishing generated UI output",
-    "allowed-tools": ["Read", "Grep", "Glob", "Bash", "Edit", "Write"]
+    "version": "1.4.0",
+    "changelog": "Added Motion-aware routing through motion-animation alongside gsap-animation; improves animation handoffs for Motion-native JavaScript and React projects; affects frontend-design motion sequencing, metadata, and catalog dependencies",
+    "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output",
+    "allowed-modes": [
+      "stack-detector",
+      "design-context-setter",
+      "component-designer",
+      "critique",
+      "visual-refiner",
+      "motion-designer"
+    ],
+    "allowed-tools": ["Read", "Grep", "Glob", "Bash", "Edit", "Write", "Task", "SubAgent"]
   },
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "agents/stack-detector.md", "kind": "asset" },
     { "path": "agents/design-context-setter.md", "kind": "asset" },
     { "path": "agents/component-designer.md", "kind": "asset" },
-    { "path": "agents/motion-designer.md", "kind": "asset" },
+    { "path": "agents/critique.md", "kind": "asset" },
     { "path": "agents/visual-refiner.md", "kind": "asset" },
+    { "path": "agents/motion-designer.md", "kind": "asset" },
     { "path": "assets/stack-scan-checklist.md", "kind": "asset" },
     { "path": "assets/aesthetic-archetypes.md", "kind": "asset" }
   ],
-  "dependencies": []
+  "dependencies": ["motion-animation", "gsap-animation"]
 }

package/catalog/skills/gsap-animation/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: "gsap-animation"
+description: "Guide GSAP animation implementation using only official GSAP documentation and the official greensock/gsap-skills source material. Trigger: implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-05-03"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added aggregate GSAP animation guidance backed by official GSAP docs and official GSAP AI skills; improves frontend motion implementation with verified timelines, ScrollTrigger, React cleanup, plugin, performance, and accessibility patterns; affects frontend animation routing and catalog discovery"
+  auto-invoke: "Implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
+# GSAP Animation Guide
+
+## When to Use
+
+Use this skill when:
+
+- The user asks for GSAP, GreenSock, JavaScript animation, advanced frontend motion, timelines, scroll-driven animation, pinning, parallax, ScrollTrigger, or React `useGSAP()`.
+- Another skill needs a verified GSAP handoff for richer UI motion than CSS transitions can comfortably express.
+- A project needs animation that is sequenced, reversible, controllable at runtime, scroll-linked, SVG-heavy, or framework-agnostic.
+
+Do not use this skill when:
+
+- The project already uses another animation library and the user has not asked to add or migrate to GSAP.
+- A simple CSS transition is sufficient and no richer timeline, scroll, plugin, or runtime control is needed.
+- The work is backend-only or has no user-facing motion surface.
+
+---
+
+## Official-Only Source Rule
+
+Before generating GSAP-specific guidance, verify the pattern against official sources in [references/official-source-map.md](references/official-source-map.md).
+
+Use only:
+
+- GSAP docs at `https://gsap.com/docs/v3/`.
+- GSAP learning/resources pages linked from the official docs.
+- The official `greensock/gsap-skills` repository linked from the GSAP docs.
+
+Do not use blog posts, snippets, Stack Overflow answers, social posts, or memory-only claims as source material for GSAP API behavior. If a detail is not covered by the reference files, check official docs before using it.
+
+---
+
+## Routing
+
+| Need | Use |
+| --- | --- |
+| One-off or simple animation | [references/core-patterns.md](references/core-patterns.md) |
+| Multi-step sequencing or runtime control | GSAP timeline guidance in [references/core-patterns.md](references/core-patterns.md) |
+| Scroll reveals, scrub, pin, snap, parallax | [references/scrolltrigger-patterns.md](references/scrolltrigger-patterns.md) |
+| React or Next.js animation | [references/react-patterns.md](references/react-patterns.md) |
+| Flip, Draggable, SplitText, SVG, ScrollSmoother, utility plugins | [references/plugin-selection.md](references/plugin-selection.md) |
+| Reduced motion, cleanup, transform performance | [references/performance-accessibility.md](references/performance-accessibility.md) |
+
+When the user asks for an animation library without naming one, prefer GSAP for timelines, scroll-driven animation, framework-agnostic animation, runtime control, or coordinated multi-element motion. If the project or user has already chosen another library, respect that choice unless they ask to compare or migrate.
+
+---
+
+## Project Preflight
+
+Always inspect the target project before proposing implementation:
+
+```bash
+grep -E '"gsap"|"@gsap/react"|"framer-motion"|"@motionone/dom"|"animejs"|"motion"' package.json
+grep -rn "gsap\\.|ScrollTrigger|useGSAP|registerPlugin" src --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" 2>/dev/null
+grep -rn "prefers-reduced-motion|transition|@keyframes" src --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" 2>/dev/null
+```
+
+If `gsap` is not installed, ask before adding it. If React `useGSAP()` is needed and `@gsap/react` is not installed, ask before adding it. This skill teaches target projects how to use GSAP; it does not add GSAP to skilly-hand itself.
+
+---
+
+## Implementation Rules
+
+- Import GSAP from the official package and register every plugin used with `gsap.registerPlugin(...)`.
+- Prefer timelines for choreography, overlap, labels, pause/play/reverse/seek control, and any sequence that would otherwise rely on chained delays.
+- Prefer GSAP transform aliases like `x`, `y`, `scale`, `rotation`, `xPercent`, `yPercent`, and `transformOrigin` over raw `transform` strings.
+- Prefer `autoAlpha` when fading elements that should become hidden and non-interactive at zero visibility.
+- Scope selectors to a component or container when working inside frameworks.
+- Clean up every component-owned animation with `useGSAP()`, `gsap.context().revert()`, or `gsap.matchMedia().revert()`.
+- Use `gsap.matchMedia()` for breakpoints and `prefers-reduced-motion`; reduce, shorten, or skip animation when users request reduced motion.
+- Avoid animating layout-heavy properties like `width`, `height`, `top`, `left`, `margin`, or `padding` when transforms can achieve the effect.
+
+---
+
+## Framework Guidance
+
+React and Next.js:
+
+- Prefer `useGSAP()` from `@gsap/react` when available.
+- Register `useGSAP` with `gsap.registerPlugin(useGSAP)`.
+- Pass a `scope` ref so selector text stays inside the component.
+- Use `contextSafe()` for event handlers, timers, or callbacks that create GSAP objects after the hook executes.
+- Keep GSAP execution in client-only lifecycle. In React Server Components, the component using GSAP must be client-side.
+
+Other frameworks:
+
+- Run GSAP setup after DOM nodes exist.
+- Scope selectors to the component root where possible.
+- Revert GSAP contexts, matchMedia instances, ScrollTriggers, and event listeners during component teardown.
+
+---
+
+## Output Contract
+
+When using this skill, include:
+
+- The official pattern source you used.
+- Whether GSAP is already installed or requires approval.
+- Which GSAP primitive is appropriate: tween, timeline, ScrollTrigger, plugin, `useGSAP()`, `context()`, or `matchMedia()`.
+- Cleanup and reduced-motion behavior.
+- A verification step appropriate to the project, such as unit tests, interaction tests, browser smoke checks, or visual inspection.
+
+---
+
+## Commands
+
+```bash
+# Install GSAP in a target project only after user approval
+npm install gsap
+
+# Install React helper only after user approval and only for React projects
+npm install @gsap/react
+
+# Check for existing GSAP usage
+grep -rn "gsap\\.|ScrollTrigger|useGSAP|registerPlugin" src --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"
+```
+
+---
+
+## Resources
+
+- Source map: [references/official-source-map.md](references/official-source-map.md)
+- Core patterns: [references/core-patterns.md](references/core-patterns.md)
+- React patterns: [references/react-patterns.md](references/react-patterns.md)
+- ScrollTrigger patterns: [references/scrolltrigger-patterns.md](references/scrolltrigger-patterns.md)
+- Plugin selection: [references/plugin-selection.md](references/plugin-selection.md)
+- Performance and accessibility: [references/performance-accessibility.md](references/performance-accessibility.md)

package/catalog/skills/gsap-animation/manifest.json

@@ -0,0 +1,30 @@
+{
+  "id": "gsap-animation",
+  "title": "GSAP Animation",
+  "description": "Guide GSAP animation implementation using only official GSAP documentation and the official greensock/gsap-skills source material. Trigger: implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation.",
+  "portable": true,
+  "tags": ["frontend", "animation", "motion", "gsap", "workflow"],
+  "detectors": ["react", "nextjs", "angular", "vite", "tailwindcss", "storybook"],
+  "detectionTriggers": ["auto"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-05-03",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added aggregate GSAP animation guidance backed by official GSAP docs and official GSAP AI skills; improves frontend motion implementation with verified timelines, ScrollTrigger, React cleanup, plugin, performance, and accessibility patterns; affects frontend animation routing and catalog discovery",
+    "auto-invoke": "Implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation",
+    "allowed-tools": ["Read", "Edit", "Write", "Glob", "Grep", "Bash", "WebFetch", "WebSearch", "Task", "SubAgent"]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "references/official-source-map.md", "kind": "reference" },
+    { "path": "references/core-patterns.md", "kind": "reference" },
+    { "path": "references/react-patterns.md", "kind": "reference" },
+    { "path": "references/scrolltrigger-patterns.md", "kind": "reference" },
+    { "path": "references/plugin-selection.md", "kind": "reference" },
+    { "path": "references/performance-accessibility.md", "kind": "reference" }
+  ],
+  "dependencies": []
+}