@skilly-hand/skilly-hand 0.25.3 → 0.26.0

package/CHANGELOG.md

@@ -16,6 +16,21 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.26.0] - 2026-05-01
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.0)
+
+### Added
+- Added dedicated performance-reviewer modes for the Angular and React guideline skills.
+
+### Changed
+- Expanded Angular and React guideline routing, review checklists, and catalog descriptions for performance optimization workflows.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.25.3] - 2026-05-01
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.3)
 

package/catalog/README.md

@@ -6,13 +6,13 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | ----- | ----------- | ---- | ------------ |
 | `accessibility-audit` | Audit web accessibility against W3C WCAG 2.2 Level AA using framework-agnostic checks, remediation patterns, and portable command-line scanning. | frontend, accessibility, workflow, quality | all |
 | `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 and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | 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 |
 | `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 |
-| `react-guidelines` | Guide React code generation and review using latest stable React verification and modern framework best practices. | react, frontend, workflow, best-practices | all |
+| `react-guidelines` | 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. | react, frontend, workflow, best-practices | all |
 | `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
 | `roaster` | Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind. | core, workflow, planning, quality | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |

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

@@ -1,13 +1,13 @@
 ---
 name: "angular-guidelines"
-description: "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices."
+description: "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."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-03"
+  last-edit: "2026-05-01"
   license: "Apache-2.0"
-  version: "1.1.1"
-  changelog: "Added allowed-modes metadata to declare angular-guidelines sub-agent routing targets; improves discoverability of component-creator and angular-tester delegation modes; affects angular-guidelines manifest metadata"
-  auto-invoke: "Generating, reviewing, or refactoring Angular code artifacts in Angular projects"
+  version: "1.2.0"
+  changelog: "Added curated official Angular skill and performance guidance with a dedicated performance-reviewer mode; improves SSR, hydration, reactivity, testing, and runtime optimization coverage; affects angular-guidelines routing, review checklists, and catalog discovery"
+  auto-invoke: "Generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects"
   allowed-tools:
     - "Read"
     - "Edit"
@@ -29,6 +29,7 @@ Use this skill when:
 - You are generating Angular components, directives, pipes, services, or supporting files.
 - You are refactoring existing Angular code to current framework patterns.
 - You are reviewing Angular code quality and framework-alignment in an Angular workspace.
+- You are optimizing Angular performance, SSR/hydration, reactivity/data flow, forms, routing, accessibility, or CLI-aligned generation.
 
 Do not use this skill for:
 
@@ -46,6 +47,7 @@ Choose sub-agents by intent:
 | --- | --- |
 | Create, refactor, or review Angular components | [agents/component-creator.md](agents/component-creator.md) |
 | Write or review Angular tests | [agents/angular-tester.md](agents/angular-tester.md) |
+| Optimize or review Angular performance, SSR, or hydration | [agents/performance-reviewer.md](agents/performance-reviewer.md) |
 
 ---
 
@@ -53,7 +55,8 @@ Choose sub-agents by intent:
 
 1. Run latest stable Angular 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, SSR, hydration, routing, data fetching, bundle size, change detection, or zoneless behavior, include the performance priority checklist.
+4. Apply the sub-agent checklist before finalizing generated code or review output.
 
 ---
 
@@ -85,13 +88,34 @@ Use these defaults unless project constraints explicitly prevent them:
 | Forms | Typed reactive forms |
 | Rendering strategy | OnPush-friendly patterns and deferred/lazy rendering where appropriate |
 
-### Pattern 3: Generation and Review Guardrails
+### Pattern 3: Modern Reactivity Guardrails
+
+- Use `computed` for derived state rather than duplicating or propagating state manually.
+- Avoid `effect` for state propagation; reserve it for logging, browser storage sync, non-template DOM work, canvas/chart integrations, or other non-reactive APIs.
+- Use `resource` for async signal-based data when the project Angular version supports it and it fits existing data patterns.
+- Use `linkedSignal` for dependent writable state when the project Angular version supports it.
+- Read signals before `await` inside reactive contexts so dependencies are tracked synchronously.
+
+### Pattern 4: Performance Review Priority
+
+Use this official-Angular-aligned priority order for performance review. Measure first when possible, then choose the smallest applicable optimization.
+
+| Priority | Review Focus | Default Action |
+| --- | --- | --- |
+| 1 | Measurement | Use Angular DevTools or Chrome DevTools Angular profiling to identify specific load, change detection, or rendering bottlenecks. |
+| 2 | Loading performance | Prefer lazy routes, `@defer` for non-critical/heavy UI, image optimization, and SSR/hydration where they improve Core Web Vitals. |
+| 3 | Runtime performance | Check zoneless change detection support, slow template/lifecycle computations, OnPush-friendly state, and zone pollution from timers or third-party code. |
+| 4 | SSR/hydration correctness | Avoid server/client template divergence, prefer platform-specific providers, keep per-request state out of shared providers, and use factory providers for request-specific values. |
+| 5 | Advanced loading | Use incremental hydration and advanced deferrable-view strategies only when the project version and UX constraints justify them. |
+
+### Pattern 5: Generation and Review Guardrails
 
 - Keep generated files focused and minimal for the requested artifact.
 - Prefer framework-native patterns over custom abstractions unless required by repo conventions.
 - Call out deprecated patterns in reviewed code and suggest modern Angular replacements.
 - For component-specific work, apply [agents/component-creator.md](agents/component-creator.md).
 - For testing-specific work, apply [agents/angular-tester.md](agents/angular-tester.md).
+- For performance-specific work, apply [agents/performance-reviewer.md](agents/performance-reviewer.md).
 
 ---
 
@@ -111,8 +135,12 @@ Is this a refactor task?
   NO  -> Continue
 
 Is this a review task?
-  YES -> Validate latest-stable alignment + best-practice checklist
+  YES -> Validate latest-stable alignment + best-practice/performance checklist
   NO  -> Apply the minimal Angular guidance needed for the request
+
+Does the task mention performance, SSR, hydration, routing, data fetching, bundles, change detection, or zoneless behavior?
+  YES -> Route through performance-reviewer before finalizing
+  NO  -> Keep the existing component/test route
 ```
 
 ---
@@ -168,6 +196,7 @@ export class ProfileService {
 - Template control flow uses modern block syntax.
 - DI and forms follow modern typed Angular practices.
 - Output avoids deprecated Angular APIs unless needed for compatibility.
+- Performance work follows measurement-first guidance and avoids speculative optimization.
 
 ---
 
@@ -196,3 +225,10 @@ ng update @angular/core @angular/cli
 - Angular update guide: https://angular.dev/update-guide
 - Angular blog (official releases): https://blog.angular.dev
 - Angular GitHub releases: https://github.com/angular/angular/releases
+- Angular Agent Skills: https://angular.dev/ai/agent-skills
+- Official Angular skills repo: https://github.com/angular/skills
+- Angular style guide: https://angular.dev/style-guide
+- Angular performance guide: https://angular.dev/best-practices/performance
+- Angular signals guide: https://angular.dev/guide/signals
+- Angular testing guide: https://angular.dev/guide/testing
+- Angular HTTP testing guide: https://angular.dev/guide/http/testing

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

@@ -29,8 +29,11 @@ Do not use this sub-agent for:
 - Test signal and computed behavior directly when possible.
 - Test signal inputs/outputs using component instance APIs and DOM-triggered events.
 - Cover async behavior with `fakeAsync`/`tick`/`flush` or `waitForAsync`/`whenStable`.
-- For HTTP paths, use `HttpClientTestingModule`/`HttpTestingController` and verify requests.
+- For HTTP paths, use `provideHttpClient()` before `provideHttpClientTesting()`, then verify requests with `HttpTestingController`.
+- Use component DOM tests when template behavior, user interaction, or child integration matters.
+- Use router testing harnesses when navigation, guards, resolvers, or routed components are the behavior under test.
 - For services, prefer explicit DI setup and clear mocking boundaries.
+- Avoid assertions on incidental implementation details unless they are part of the public contract.
 
 ---
 
@@ -99,12 +102,17 @@ describe("CounterComponent", () => {
 
 ```typescript
 import { TestBed } from "@angular/core/testing";
-import { HttpClientTestingModule, HttpTestingController } from "@angular/common/http/testing";
+import { provideHttpClient } from "@angular/common/http";
+import { provideHttpClientTesting, HttpTestingController } from "@angular/common/http/testing";
 
 describe("ProfileService", () => {
   it("requests profile", () => {
     TestBed.configureTestingModule({
-      imports: [HttpClientTestingModule]
+      providers: [
+        ProfileService,
+        provideHttpClient(),
+        provideHttpClientTesting()
+      ]
     });
     const service = TestBed.inject(ProfileService);
     const httpMock = TestBed.inject(HttpTestingController);
@@ -127,4 +135,6 @@ describe("ProfileService", () => {
 - Standalone Angular artifacts are tested with appropriate TestBed setup.
 - Signal/input/output behavior is asserted explicitly.
 - Async and HTTP behavior use deterministic Angular testing utilities.
+- HTTP tests use provider-based setup with `provideHttpClient()` before `provideHttpClientTesting()` for new code.
+- Router behavior uses harness-style tests where the workspace supports them.
 - Assertions verify user-visible behavior or contract-level outcomes, not incidental internals.

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

@@ -27,6 +27,18 @@ Do not use this sub-agent for:
 
 ---
 
+## Style and Reactivity Checklist
+
+- Prefer feature-based organization and one primary Angular concept per file.
+- Use `protected` for class members that are only read by the template.
+- Mark Angular-managed properties `readonly`, including `input`, `model`, `output`, and query values.
+- Prefer `[class]` and `[style]` bindings over `ngClass` and `ngStyle`.
+- Move complex template logic into TypeScript, usually as a `computed`.
+- Use `computed` for derived state and avoid `effect` for state propagation.
+- Use `resource` or `linkedSignal` only when the project Angular version supports them and they fit existing data patterns.
+
+---
+
 ## Template Snippets
 
 ### Minimal Standalone Component
@@ -122,3 +134,4 @@ export class CardComponent {
 - Templates use native control flow blocks, not legacy structural directives.
 - Host interaction includes required ARIA and keyboard semantics for interactive UI.
 - Change detection and state flow are OnPush-friendly and predictable.
+- Template-only members are `protected`, Angular-managed fields are `readonly`, and complex template logic is moved into `computed` values.

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

@@ -0,0 +1,62 @@
+# Angular Performance Reviewer
+
+## When to Use
+
+Use this sub-agent when:
+
+- Reviewing or improving Angular loading, runtime, change detection, or rendering performance.
+- Working on SSR, hydration, incremental hydration, `@defer`, lazy routes, image optimization, or bundle size.
+- Investigating slow interactions, excessive change detection, zone pollution, slow template expressions, or lifecycle bottlenecks.
+
+Do not use this sub-agent for:
+
+- Pure test-only tasks without performance behavior.
+- Non-Angular frontend performance work.
+- Speculative rewrites where no user-visible or measured bottleneck exists.
+
+---
+
+## Priority Checklist
+
+Work from highest signal to lowest. Stop once the request is solved; do not add unrelated optimizations.
+
+| Priority | Focus | Checks |
+| --- | --- | --- |
+| 1 | Measurement | Use Angular DevTools or Chrome DevTools Angular profiling to identify load, change detection, rendering, or lifecycle bottlenecks before changing code when practical. |
+| 2 | Loading performance | Prefer lazy routes for route-level splitting, `@defer` for non-critical or heavy UI, image optimization for visual content, and SSR/hydration for content-heavy or SEO-sensitive pages. |
+| 3 | Runtime performance | Check zoneless change detection support, OnPush-friendly state flow, slow template expressions, expensive lifecycle hooks, and zone pollution from timers or third-party libraries. |
+| 4 | SSR/hydration correctness | Keep server and client rendered content consistent, avoid browser-only conditionals in templates, use platform-specific providers, and prevent shared module/provider state from leaking across requests. |
+| 5 | Advanced loading | Use incremental hydration, custom `@defer` triggers, prefetching, or worker offloading only when the project version, bottleneck, and UX constraints justify them. |
+
+---
+
+## SSR and Hydration Guardrails
+
+- Avoid rendering different template content on server and client; mismatches can hurt hydration and layout stability.
+- Use `afterNextRender` or platform-specific providers for browser-only initialization instead of template-level platform checks.
+- Use factory providers for request-specific values on the server; avoid shared `useValue` objects for per-request data.
+- Keep `@defer` placeholders accessible and avoid deferring initially visible content unless incremental hydration and layout constraints are handled.
+- Avoid nested `@defer` blocks with identical eager triggers that cause cascading loads.
+
+---
+
+## Reactivity and Change Detection Guardrails
+
+- Use signals and `computed` values for local derived state.
+- Avoid `effect` for propagating state changes; reserve it for side effects against non-reactive APIs.
+- Read signals before `await` inside reactive contexts.
+- Prefer OnPush-friendly inputs and immutable data flow in zone-based apps.
+- In zoneless-ready apps, avoid assumptions that depend on ZoneJS side effects.
+
+---
+
+## 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: Angular DevTools, Chrome DevTools Angular profiling, bundle output, Core Web Vitals, targeted test, or existing project command.
+
+If no meaningful performance issue is found, say so and avoid inventing speculative work.

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

@@ -1,7 +1,7 @@
 {
   "id": "angular-guidelines",
   "title": "Angular Guidelines",
-  "description": "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices.",
+  "description": "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.",
   "portable": true,
   "tags": ["angular", "frontend", "workflow", "best-practices"],
   "detectors": ["angular"],
@@ -10,14 +10,15 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-03",
+    "last-edit": "2026-05-01",
     "license": "Apache-2.0",
-    "version": "1.1.1",
-    "changelog": "Added allowed-modes metadata to declare angular-guidelines sub-agent routing targets; improves discoverability of component-creator and angular-tester delegation modes; affects angular-guidelines manifest metadata",
-    "auto-invoke": "Generating, reviewing, or refactoring Angular code artifacts in Angular projects",
+    "version": "1.2.0",
+    "changelog": "Added curated official Angular skill and performance guidance with a dedicated performance-reviewer mode; improves SSR, hydration, reactivity, testing, and runtime optimization coverage; affects angular-guidelines routing, review checklists, and catalog discovery",
+    "auto-invoke": "Generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects",
     "allowed-modes": [
       "component-creator",
-      "angular-tester"
+      "angular-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/angular-tester.md", "kind": "instruction" }
+    { "path": "agents/angular-tester.md", "kind": "instruction" },
+    { "path": "agents/performance-reviewer.md", "kind": "instruction" }
   ],
   "dependencies": []
 }

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.0",
   "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.0",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

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

package/packages/detectors/package.json

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