@skilly-hand/skilly-hand 0.25.3 → 0.26.1

package/catalog/skills/react-guidelines/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "react-guidelines"
-description: "Guide React code generation and review using latest stable React verification and modern framework best practices."
+description: "Guide React and Next.js code generation, review, and performance tuning using latest stable React verification and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing React code artifacts in React projects."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-04"
+  last-edit: "2026-05-01"
   license: "Apache-2.0"
-  version: "1.0.0"
-  changelog: "Added new react-guidelines skill with component and testing sub-agent routing; improves React-specific generation and review consistency with latest-stable preflight checks; affects portable catalog skill discovery and React workflow guidance"
-  auto-invoke: "Generating, reviewing, or refactoring React code artifacts in React projects"
+  version: "1.1.0"
+  changelog: "Added curated Vercel-style React and Next.js performance review guidance with a dedicated performance-reviewer mode; improves async, bundle, server, client data, and rendering optimization coverage; affects react-guidelines routing, review checklists, and catalog discovery"
+  auto-invoke: "Generating, reviewing, refactoring, or optimizing React code artifacts in React projects"
   allowed-tools:
     - "Read"
     - "Edit"
@@ -29,6 +29,7 @@ Use this skill when:
 - You are generating React components, hooks, or supporting modules.
 - You are refactoring existing React code to current framework patterns.
 - You are reviewing React code quality and framework-alignment in a React workspace.
+- You are optimizing React or Next.js behavior around async work, bundle size, data fetching, server/client boundaries, or rendering cost.
 
 Do not use this skill for:
 
@@ -46,6 +47,7 @@ Choose sub-agents by intent:
 | --- | --- |
 | Create, refactor, or review React components | [agents/component-creator.md](agents/component-creator.md) |
 | Write or review React tests | [agents/react-tester.md](agents/react-tester.md) |
+| Optimize or review React/Next.js performance | [agents/performance-reviewer.md](agents/performance-reviewer.md) |
 
 ---
 
@@ -53,7 +55,8 @@ Choose sub-agents by intent:
 
 1. Run latest stable React preflight checks.
 2. Route to the smallest matching sub-agent by task intent.
-3. Apply the sub-agent checklist before finalizing generated code or review output.
+3. If the request mentions performance, Next.js, data fetching, server/client boundaries, bundles, or re-renders, include the performance priority checklist.
+4. Apply the sub-agent checklist before finalizing generated code or review output.
 
 ---
 
@@ -94,6 +97,22 @@ Use these defaults unless project constraints explicitly prevent them:
 - Keep state minimal and colocated near usage.
 - For component-specific work, apply [agents/component-creator.md](agents/component-creator.md).
 - For testing-specific work, apply [agents/react-tester.md](agents/react-tester.md).
+- For performance-specific work, apply [agents/performance-reviewer.md](agents/performance-reviewer.md).
+
+### Pattern 4: Performance Review Priority
+
+Use this Vercel-style priority order for React and Next.js performance review. Start with the highest-impact item that applies to the request; do not add complexity for hypothetical bottlenecks.
+
+| Priority | Review Focus | Default Action |
+| --- | --- | --- |
+| 1 | Eliminating waterfalls | Start independent promises early, defer awaits until values are needed, and use `Promise.all` for independent async work. |
+| 2 | Bundle size optimization | Avoid problematic barrel imports unless tooling optimizes them, dynamically import heavy or client-only modules, and defer third-party libraries. |
+| 3 | Server-side performance | Authenticate server actions, avoid shared request state, minimize client-component serialization, and use per-request dedupe where applicable. |
+| 4 | Client-side data fetching | Dedupe repeated requests, keep global listeners passive and cleaned up, and keep browser storage minimal and versioned. |
+| 5 | Re-render optimization | Derive state during render, avoid redundant state, keep non-primitive defaults stable, and memoize only when it removes measured churn. |
+| 6 | Rendering performance | Split expensive work, place Suspense boundaries around meaningful async UI, and use transitions/deferred values for user-visible responsiveness. |
+| 7 | JavaScript performance | Keep hot-path work small, avoid repeated parsing or allocation in render paths, and prefer platform APIs over bulky helpers where practical. |
+| 8 | Advanced patterns | Use virtualization, streaming, caching, or compiler-aware patterns only when the project stack and bottleneck justify them. |
 
 ---
 
@@ -113,8 +132,12 @@ Is this a refactor task?
   NO  -> Continue
 
 Is this a review task?
-  YES -> Validate latest-stable alignment + hook/purity checklist
+  YES -> Validate latest-stable alignment + hook/purity/performance checklist
   NO  -> Apply the minimal React guidance needed for the request
+
+Does the task mention performance, Next.js, data fetching, bundles, RSC, or re-renders?
+  YES -> Route through performance-reviewer before finalizing
+  NO  -> Keep the existing component/test route
 ```
 
 ---
@@ -170,6 +193,7 @@ export function UserPanelClient({ name }: { name: string }) {
 - Hooks follow call-order rules and purity constraints.
 - `'use client'`/`'use server'` directives are only used where boundary semantics require them.
 - Suspense/StrictMode/Profiler guidance is considered when relevant to behavior.
+- Performance work follows the priority order from waterfalls through advanced patterns and avoids speculative optimization.
 
 ---
 
@@ -208,3 +232,4 @@ npm run catalog:check
 - StrictMode: https://react.dev/reference/react/StrictMode
 - Fragment: https://react.dev/reference/react/Fragment
 - Profiler: https://react.dev/reference/react/Profiler
+- Vercel Labs React best practices skill: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices

package/catalog/skills/react-guidelines/agents/component-creator.md

@@ -28,6 +28,17 @@ Do not use this sub-agent for:
 
 ---
 
+## Performance Checklist
+
+- Do not define child components inside render; move them to module scope unless they truly need closure state.
+- Do not store redundant derived state; derive from props/state during render.
+- Avoid unnecessary Effects for synchronous derivation or event handling.
+- Keep default non-primitive props stable by defining fallback arrays/objects/functions at module scope.
+- Use Suspense, transitions, deferred values, and memoization only when they improve a real user-visible or measured bottleneck.
+- In Next.js, keep client components narrow and pass only serializable data across server/client boundaries.
+
+---
+
 ## Template Snippets
 
 ### Minimal Pure Function Component
@@ -86,3 +97,4 @@ export function ProfileSection() {
 - Composition is preferred over inheritance or over-abstraction.
 - Client/server boundary directives are correctly scoped.
 - Accessibility semantics are present for interactive controls.
+- Component shape avoids preventable re-renders, redundant state, and unstable default values.

package/catalog/skills/react-guidelines/agents/performance-reviewer.md

@@ -0,0 +1,55 @@
+# React Performance Reviewer
+
+## When to Use
+
+Use this sub-agent when:
+
+- Reviewing or improving React or Next.js performance.
+- Working on async data fetching, Suspense, streaming, server actions, RSC boundaries, bundle size, or client/server splits.
+- Investigating avoidable re-renders, slow interactions, heavy imports, or expensive render-time JavaScript.
+
+Do not use this sub-agent for:
+
+- Pure test-only tasks without performance behavior.
+- Non-React frontend performance work.
+- Speculative rewrites where no user-visible or measured bottleneck exists.
+
+---
+
+## Priority Checklist
+
+Work from highest impact to lowest. Stop once the request is solved; do not add unrelated optimizations.
+
+| Priority | Focus | Checks |
+| --- | --- | --- |
+| 1 | Eliminating waterfalls | Start independent async work before awaiting dependencies; use `Promise.all` for independent requests; fetch at the highest useful boundary. |
+| 2 | Bundle size optimization | Avoid unoptimized barrel imports; dynamically import heavy/client-only code; defer analytics, editors, charts, maps, and other third-party libraries. |
+| 3 | Server-side performance | Authenticate server actions; avoid module-level mutable request state; minimize serialized props sent to client components; dedupe per request where supported. |
+| 4 | Client-side data fetching | Dedupe repeated requests; cancel or ignore stale async work; clean up global listeners; keep passive listeners passive; keep browser storage minimal and versioned. |
+| 5 | Re-render optimization | Remove redundant derived state; avoid nested component definitions; stabilize non-primitive defaults; use `memo`, `useMemo`, and `useCallback` only for proven churn. |
+| 6 | Rendering performance | Split expensive UI; use Suspense boundaries with meaningful fallbacks; use transitions or deferred values for responsiveness during expensive updates. |
+| 7 | JavaScript performance | Move expensive parsing/allocation out of render hot paths; prefer smaller platform APIs over bulky helpers; avoid repeated work in loops and render paths. |
+| 8 | Advanced patterns | Add virtualization, streaming, caching layers, compiler-aware patterns, or worker offloading only when the project stack and bottleneck justify them. |
+
+---
+
+## Next.js Guardrails
+
+- Keep server components as the default for data-heavy UI; add `'use client'` only for interactivity or browser-only APIs.
+- Treat server actions as public endpoints: validate input, authenticate/authorize, and avoid leaking server-only data to client props.
+- Keep request-specific state inside the request scope; do not store user/session/request data in shared module variables.
+- Pass compact, serializable props from server to client components.
+- Prefer framework-supported request caching and dedupe over ad hoc global caches.
+
+---
+
+## Review Output
+
+When reviewing performance, report:
+
+1. Highest-impact issue first, tied to the priority checklist.
+2. Concrete code-level recommendation using existing project patterns.
+3. Expected user-visible or measurable benefit.
+4. Verification path: profiler trace, bundle analyzer, network waterfall, targeted test, or existing project command.
+
+If no meaningful performance issue is found, say so and avoid inventing speculative work.

package/catalog/skills/react-guidelines/agents/react-tester.md

@@ -33,6 +33,16 @@ Do not use this sub-agent for:
 
 ---
 
+## Performance-Sensitive Test Patterns
+
+- Assert user-visible async states instead of timing or scheduler internals.
+- Cover Suspense fallback and resolved UI when the component owns a meaningful async boundary.
+- Test deduped fetch or request behavior only when the project already exposes a stable cache/dedupe contract.
+- For transitions and deferred values, assert responsiveness and final visible output, not React implementation details.
+- Avoid tests that lock in incidental render counts unless render count is the public performance contract.
+
+---
+
 ## Command Matrix
 
 | Scenario | Preferred Command | Fallback |
@@ -108,4 +118,5 @@ it("shows fallback before async content resolves", () => {
 - `act`-safe patterns are preserved for stateful and async updates.
 - Assertions validate user-visible behavior and contracts.
 - Suspense/transition scenarios are tested where relevant.
+- Performance-sensitive tests avoid scheduler internals and incidental render-count assertions.
 - Mocks are limited to necessary boundaries.

package/catalog/skills/react-guidelines/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "react-guidelines",
   "title": "React Guidelines",
-  "description": "Guide React code generation and review using latest stable React verification and modern framework best practices.",
+  "description": "Guide React and Next.js code generation, review, and performance tuning using latest stable React verification and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing React code artifacts in React projects.",
   "portable": true,
   "tags": ["react", "frontend", "workflow", "best-practices"],
   "detectors": ["react"],
@@ -10,14 +10,15 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-04",
+    "last-edit": "2026-05-01",
     "license": "Apache-2.0",
-    "version": "1.0.0",
-    "changelog": "Added new react-guidelines skill with component and testing sub-agent routing; improves React-specific generation and review consistency with latest-stable preflight checks; affects portable catalog skill discovery and React workflow guidance",
-    "auto-invoke": "Generating, reviewing, or refactoring React code artifacts in React projects",
+    "version": "1.1.0",
+    "changelog": "Added curated Vercel-style React and Next.js performance review guidance with a dedicated performance-reviewer mode; improves async, bundle, server, client data, and rendering optimization coverage; affects react-guidelines routing, review checklists, and catalog discovery",
+    "auto-invoke": "Generating, reviewing, refactoring, or optimizing React code artifacts in React projects",
     "allowed-modes": [
       "component-creator",
-      "react-tester"
+      "react-tester",
+      "performance-reviewer"
     ],
     "allowed-tools": [
       "Read",
@@ -35,7 +36,8 @@
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "agents/component-creator.md", "kind": "instruction" },
-    { "path": "agents/react-tester.md", "kind": "instruction" }
+    { "path": "agents/react-tester.md", "kind": "instruction" },
+    { "path": "agents/performance-reviewer.md", "kind": "instruction" }
   ],
   "dependencies": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.25.3",
+  "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.25.3",
+  "version": "0.26.1",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

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

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.25.3",
+  "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.25.3",
+  "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));
 }