@skilly-hand/skilly-hand 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -16,6 +16,23 @@ All notable changes to this project are documented in this file.
 ### 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/catalog/README.md

@@ -8,7 +8,8 @@ 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 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 |
 | `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,7 @@
   "angular-guidelines",
   "figma-mcp-0to1",
   "frontend-design",
+  "gsap-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 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.3.0"
+  changelog: "Added GSAP-aware motion routing through gsap-animation while preserving critique workflow; improves advanced frontend animation handoffs with official-source GSAP guidance; 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, preferring GSAP handoff for advanced motion | [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. For timelines, scroll reveals, richer micro-interactions, lifecycle-safe framework animation, or plugin decisions, route through `gsap-animation`.
 
 ---
 
@@ -190,8 +194,12 @@ 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 need timelines, ScrollTrigger, framework cleanup, or plugins?
+            YES -> Use gsap-animation for official-source GSAP guidance
+            NO  -> Use confirmed stack primitives
 ```
 
 ---
@@ -275,7 +283,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,8 @@
 
 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 advanced 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 timelines, scroll-driven reveals, richer micro-interactions, framework lifecycle cleanup, and GSAP plugin decisions.
+
 ---
 
 ## When to Use
@@ -40,7 +42,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 +56,8 @@ 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 the user wants a JavaScript animation library or the motion needs timeline sequencing, scroll-driven animation, pinning, scrub, advanced SVG/text/UI plugins, or framework-agnostic runtime control, recommend GSAP and 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 +105,18 @@ 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. 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.
+- React, Next.js, Vue, Svelte, or Angular animation that needs 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 +192,7 @@ 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.
+- [ ] Advanced GSAP-suitable motion 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 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.3.0",
+    "changelog": "Added GSAP-aware motion routing through gsap-animation while preserving critique workflow; improves advanced frontend animation handoffs with official-source GSAP guidance; 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": ["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": []
+}

package/catalog/skills/gsap-animation/references/core-patterns.md

@@ -0,0 +1,61 @@
+# GSAP Core Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/
+- https://gsap.com/docs/v3/Installation/
+- https://gsap.com/docs/v3/GSAP/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-core/SKILL.md
+
+## Selection
+
+Use GSAP core when the motion needs JavaScript control, runtime values, coordinated targets, SVG/DOM animation, or choreography that is awkward in CSS. Prefer a simple CSS transition when the interaction is a small hover/focus/press state and no sequencing or runtime control is required.
+
+When the user asks for a JavaScript animation library without specifying one, recommend GSAP when the need includes timelines, scroll-driven animation, runtime control, coordinated multi-element motion, or framework-agnostic reuse.
+
+## Installation and Imports
+
+For package-managed projects, the official install command is:
+
+```bash
+npm install gsap
+```
+
+Use module imports in bundled projects:
+
+```js
+import { gsap } from "gsap";
+```
+
+Ask before adding the dependency when it is not already present.
+
+## Tweens
+
+Use tweens for simple one-step animation:
+
+- `gsap.to(targets, vars)`: animate from current values to `vars`.
+- `gsap.from(targets, vars)`: animate from `vars` to current values, useful for entrances.
+- `gsap.fromTo(targets, fromVars, toVars)`: explicitly define both start and end.
+- `gsap.set(targets, vars)`: set values immediately.
+
+Store the returned tween when playback must be controlled later.
+
+## Timelines
+
+Use timelines for sequences, overlap, labels, modular choreography, or playback control. Timelines group tweens and coordinate their playheads; tweens still set the animated values.
+
+Prefer a timeline over stacking multiple `delay` values. Use the position parameter for offsets and overlaps, and labels when named positions make later control easier.
+
+## Properties and Values
+
+- Use camelCase property names in GSAP vars.
+- Prefer GSAP transform aliases: `x`, `y`, `z`, `xPercent`, `yPercent`, `scale`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`.
+- Prefer `autoAlpha` when fading elements that should also stop being visible/interactable at zero.
+- Use `stagger` for offset sibling animation.
+- Use documented ease strings like `none`, `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, and `sine`, with `.in`, `.out`, or `.inOut` variants when appropriate.
+
+## Cleanup
+
+For component-owned GSAP code, create animations inside `gsap.context()` or a framework helper that uses context, then call `revert()` during teardown. See [react-patterns.md](react-patterns.md) and [performance-accessibility.md](performance-accessibility.md).

package/catalog/skills/gsap-animation/references/official-source-map.md

@@ -0,0 +1,31 @@
+# Official GSAP Source Map
+
+Extracted: 2026-05-03
+
+This skill may only use official GSAP sources. The official GSAP docs page links the official `greensock/gsap-skills` repository as "AI Skills", so that repository is accepted as source material for agent-oriented guidance.
+
+## Primary Sources
+
+| Source | Use |
+| --- | --- |
+| https://gsap.com/docs/v3/ | Documentation index, GSAP version navigation, core/plugin taxonomy, official AI Skills link |
+| https://gsap.com/docs/v3/Installation/ | Package installation, module/script options, plugin registration FAQ, public npm package guidance |
+| https://gsap.com/docs/v3/GSAP/ | Core object, tweens, timelines, sequencing, control methods |
+| https://gsap.com/docs/v3/GSAP/gsap.context()/ | Context scoping and cleanup with `revert()` |
+| https://gsap.com/docs/v3/GSAP/gsap.matchMedia()/ | Responsive conditions, cleanup, and `prefers-reduced-motion` handling |
+| https://gsap.com/docs/v3/Plugins/ScrollTrigger/ | ScrollTrigger registration, tween/timeline usage, pin, scrub, snap, callbacks |
+| https://gsap.com/resources/React/ | React `useGSAP()`, scope, cleanup, SSR/client guidance, `contextSafe()` |
+| https://github.com/greensock/gsap-skills | Official AI skill repository linked from GSAP docs |
+
+## Official AI Skill Sources
+
+| Source | Use |
+| --- | --- |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-core/SKILL.md | Agent-oriented core tween, transform, easing, `matchMedia()`, and recommendation guidance |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-react/SKILL.md | Agent-oriented React, `useGSAP()`, context, cleanup, SSR, and callback guidance |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-scrolltrigger/SKILL.md | Agent-oriented ScrollTrigger registration, scroll-linked animation, pin, scrub, and cleanup guidance |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-performance/SKILL.md | Agent-oriented transform/performance cautions |
+
+## Verification Rule
+
+When a GSAP API or behavior is not represented in these local reference files, check the official docs before generating implementation guidance. If the official docs conflict with a local reference, the official docs page wins and this skill should be updated.

package/catalog/skills/gsap-animation/references/performance-accessibility.md

@@ -0,0 +1,61 @@
+# GSAP Performance and Accessibility
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/GSAP/gsap.context()/
+- https://gsap.com/docs/v3/GSAP/gsap.matchMedia()/
+- https://gsap.com/resources/React/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-core/SKILL.md
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-performance/SKILL.md
+
+## Cleanup
+
+Use `gsap.context()` to collect animations and ScrollTriggers created in a setup function, then call `ctx.revert()` during teardown. Context can also scope selector text to a root element or ref.
+
+In React, prefer `useGSAP()` when available because it uses context-style cleanup automatically. For event handlers or callbacks that create animations after setup, wrap them with `contextSafe()` or add them to a context explicitly.
+
+Use `gsap.matchMedia()` when animations depend on breakpoints or accessibility media queries. Call `mm.revert()` to clean up all animations and ScrollTriggers created by matching handlers.
+
+## Reduced Motion
+
+Respect `prefers-reduced-motion`. Use `gsap.matchMedia()` with a named condition such as:
+
+```js
+const mm = gsap.matchMedia();
+
+mm.add({
+  isDesktop: "(min-width: 800px)",
+  reduceMotion: "(prefers-reduced-motion: reduce)"
+}, (context) => {
+  const { reduceMotion } = context.conditions;
+
+  if (reduceMotion) {
+    gsap.set(".panel", { autoAlpha: 1, y: 0 });
+    return;
+  }
+
+  gsap.from(".panel", { autoAlpha: 0, y: 24, duration: 0.6 });
+});
+```
+
+Reduced-motion behavior may set final states immediately, shorten motion to near-zero duration, or skip non-essential animation.
+
+## Performance
+
+- Prefer transform aliases and opacity/`autoAlpha` for UI motion.
+- Avoid layout-heavy properties when transforms can achieve the same visual result.
+- Avoid raw `transform` strings when GSAP transform aliases communicate the intent more clearly.
+- Store tween/timeline instances only when control is needed; otherwise keep animation setup inside cleanup-aware contexts.
+- For ScrollTrigger, refresh after layout changes that alter trigger positions.
+
+## Review Checklist
+
+- [ ] GSAP dependency additions were approved.
+- [ ] Plugins are imported and registered before use.
+- [ ] Component-owned animations are cleaned up.
+- [ ] Selector text is scoped in framework components.
+- [ ] Reduced-motion users get static, skipped, or simplified motion.
+- [ ] Timelines are used for sequences instead of chained delay values.
+- [ ] Transform aliases and `autoAlpha` are preferred where they fit.

package/catalog/skills/gsap-animation/references/plugin-selection.md

@@ -0,0 +1,42 @@
+# GSAP Plugin Selection
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/
+- https://gsap.com/docs/v3/Installation/
+- https://gsap.com/docs/v3/Plugins/
+- https://github.com/greensock/gsap-skills
+
+## Rule
+
+Use the smallest GSAP surface that solves the motion problem. Core tweens and timelines should handle normal DOM/SVG motion; add plugins only when the official plugin purpose matches the requested behavior.
+
+Register every plugin used with `gsap.registerPlugin(...)`. Official installation guidance recommends registration in module environments so build tools do not drop plugins during tree shaking.
+
+## Selection Matrix
+
+| Need | Official GSAP Tool |
+| --- | --- |
+| Scroll-triggered playback, scrub, pin, snap, scroll callbacks | `ScrollTrigger` |
+| Smooth scrolling built on native scroll behavior | `ScrollSmoother` |
+| Scroll to an element or position | `ScrollToPlugin` |
+| State-to-state UI transitions and layout changes | `Flip` |
+| Drag interactions | `Draggable` |
+| Momentum/inertia behavior | `InertiaPlugin` |
+| Pointer/touch/wheel intent observation | `Observer` |
+| Text splitting for animation | `SplitText` |
+| Scrambled text effects | `ScrambleTextPlugin` |
+| SVG shape drawing | `DrawSVGPlugin` |
+| SVG shape morphing | `MorphSVGPlugin` |
+| Motion along SVG paths | `MotionPathPlugin` |
+| Custom easing curves | `CustomEase` |
+| Development-time animation inspection | `GSDevTools` |
+
+## Guardrails
+
+- Do not add a plugin for a task core GSAP can solve clearly.
+- Do not register unused plugins.
+- Do not introduce scroll smoothing, draggable, inertia, or text-splitting behavior as decorative polish without user approval.
+- Check official docs when selecting a plugin not listed in this matrix.

package/catalog/skills/gsap-animation/references/react-patterns.md

@@ -0,0 +1,59 @@
+# GSAP React Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/resources/React/
+- https://gsap.com/docs/v3/GSAP/gsap.context()/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-react/SKILL.md
+
+## Use `useGSAP()` When Available
+
+For React and Next.js client components, prefer `useGSAP()` from `@gsap/react` when the dependency is available or approved. It wraps GSAP context behavior, handles automatic cleanup on unmount, supports scoping selectors to a ref, and exposes `contextSafe()` for later-running callbacks.
+
+Ask before installing `@gsap/react` if it is not already present.
+
+```js
+import { useRef } from "react";
+import { gsap } from "gsap";
+import { useGSAP } from "@gsap/react";
+
+gsap.registerPlugin(useGSAP);
+
+function Example() {
+  const container = useRef(null);
+
+  useGSAP(() => {
+    gsap.to(".box", { x: 100 });
+  }, { scope: container });
+
+  return <div ref={container}><div className="box" /></div>;
+}
+```
+
+## Scope and Refs
+
+Pass a `scope` ref or element when using selector text. This keeps `.box`, `.item`, and similar selectors inside the component root. Without scoping, selectors can match elements outside the component.
+
+Use direct refs when a target is unique or when selector text would be ambiguous.
+
+## Dependencies and Updates
+
+`useGSAP()` accepts either a dependency array or a config object. Use the config object when you need `scope`, `dependencies`, or `revertOnUpdate`.
+
+Use `revertOnUpdate: true` when dependency changes should tear down and rebuild GSAP objects instead of preserving them until unmount.
+
+## Context-Safe Callbacks
+
+Animations created after the hook body runs, such as inside event handlers, timers, or callbacks, are not automatically captured unless wrapped. Use `contextSafe()` so GSAP objects created later are tied to the same cleanup context.
+
+When manually adding event listeners, return cleanup that removes the listeners.
+
+## SSR and Next.js
+
+GSAP manipulates browser-side targets. Keep GSAP execution inside client-only lifecycle such as `useGSAP()` or `useEffect()`. In React Server Components or Next app router usage, place GSAP code in a client component.
+
+## Fallback Without `@gsap/react`
+
+If `@gsap/react` is not used, create a `gsap.context()` inside an effect and call `ctx.revert()` in cleanup. Pass the component ref as scope.

package/catalog/skills/gsap-animation/references/scrolltrigger-patterns.md

@@ -0,0 +1,61 @@
+# GSAP ScrollTrigger Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/Plugins/ScrollTrigger/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-scrolltrigger/SKILL.md
+
+## When to Use
+
+Use ScrollTrigger for scroll-driven animation, scroll reveals, scrubbed timelines, pinned sections, snapping, parallax-style effects, or callbacks based on scroll position. Prefer it when no other scroll animation library has already been chosen.
+
+## Registration
+
+ScrollTrigger is a GSAP plugin. Import and register it before use in module-based projects:
+
+```js
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+gsap.registerPlugin(ScrollTrigger);
+```
+
+## Basic Patterns
+
+Attach a simple trigger to a tween when animation should start as an element enters the viewport:
+
+```js
+gsap.to(".box", {
+  scrollTrigger: ".box",
+  x: 500
+});
+```
+
+Attach ScrollTrigger to a timeline for coordinated scroll-linked animation:
+
+```js
+const tl = gsap.timeline({
+  scrollTrigger: {
+    trigger: ".section",
+    start: "top top",
+    end: "+=500",
+    scrub: true,
+    pin: true
+  }
+});
+
+tl.from(".title", { autoAlpha: 0, y: 24 })
+  .to(".panel", { xPercent: -100 });
+```
+
+Use `ScrollTrigger.create()` for standalone callbacks or scroll state without attaching directly to a tween.
+
+## Cleanup and Refresh
+
+Create ScrollTriggers inside `useGSAP()`, `gsap.context()`, or `gsap.matchMedia()` so they are reverted during teardown. After DOM or layout changes that affect trigger positions, call `ScrollTrigger.refresh()` from the appropriate lifecycle point.
+
+## Reduced Motion
+
+Use `gsap.matchMedia()` to gate scroll-triggered motion when `prefers-reduced-motion: reduce` matches. For reduced motion users, skip scrub/pin choreography or replace it with a static end state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "repository": {

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "private": true,
   "type": "module"
 }

package/packages/core/src/index.js

@@ -269,6 +269,26 @@ function parseSkillIds(input) {
   return uniq((input || []).flatMap((value) => String(value).split(",")).map((value) => value.trim()).filter(Boolean));
 }
 
+function expandSkillDependencies({ catalog, skillIds }) {
+  const byId = new Map(catalog.filter((skill) => skill.portable).map((skill) => [skill.id, skill]));
+  const expanded = new Set(skillIds);
+  const pending = [...skillIds];
+
+  while (pending.length > 0) {
+    const skillId = pending.pop();
+    const skill = byId.get(skillId);
+    if (!skill || !Array.isArray(skill.dependencies)) continue;
+
+    for (const dependencyId of skill.dependencies) {
+      if (!byId.has(dependencyId) || expanded.has(dependencyId)) continue;
+      expanded.add(dependencyId);
+      pending.push(dependencyId);
+    }
+  }
+
+  return expanded;
+}
+
 export function resolveSkillSelectionByIds({ catalog, selectedSkillIds = [] }) {
   const ids = parseSkillIds(selectedSkillIds);
   const portableById = new Map(
@@ -293,7 +313,9 @@ export function resolveSkillSelectionByIds({ catalog, selectedSkillIds = [] }) {
     throw new Error(invalid.join("; "));
   }
 
-  return ids.map((id) => portableById.get(id)).sort((a, b) => a.id.localeCompare(b.id));
+  const expanded = expandSkillDependencies({ catalog, skillIds: ids });
+
+  return [...expanded].map((id) => portableById.get(id)).sort((a, b) => a.id.localeCompare(b.id));
 }
 
 export function resolveSkillSelection({ catalog, detections, includeTags = [], excludeTags = [] }) {
@@ -306,7 +328,8 @@ export function resolveSkillSelection({ catalog, detections, includeTags = [], e
     }
   }
 
-  let selected = catalog.filter((skill) => requested.has(skill.id) && skill.portable);
+  const expanded = expandSkillDependencies({ catalog, skillIds: [...requested] });
+  let selected = catalog.filter((skill) => expanded.has(skill.id) && skill.portable);
 
   if (includeTags.length > 0) {
     selected = selected.filter((skill) => includeTags.every((tag) => skill.tags.includes(tag)));

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "private": true,
   "type": "module"
 }

package/packages/detectors/src/index.js

@@ -187,6 +187,15 @@ export async function detectProject(cwd) {
     });
   }
 
+  if ("gsap" in deps || "@gsap/react" in deps) {
+    addDetection(results, {
+      technology: "gsap",
+      confidence: 0.95,
+      reasons: ['Dependency "gsap" or "@gsap/react" found in package.json'],
+      recommendedSkillIds: ["gsap-animation"]
+    });
+  }
+
   return results.sort((a, b) => b.confidence - a.confidence || a.technology.localeCompare(b.technology));
 }