@skilly-hand/skilly-hand 0.25.2 → 0.26.0

package/CHANGELOG.md

@@ -16,6 +16,36 @@ 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)
+
+### Added
+- _None._
+
+### Changed
+- Refreshed the `figma-mcp-0to1` skill with current Figma MCP tools, setup commands, agent coverage notes, Make resources, and trusted workflow guidance.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.25.2] - 2026-04-29
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.2)
 

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/figma-mcp-0to1/SKILL.md

@@ -3,10 +3,10 @@ name: "figma-mcp-0to1"
 description: "Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-03"
+  last-edit: "2026-05-01"
   license: "Apache-2.0"
-  version: "1.0.1"
-  changelog: "Added allowed-modes metadata to declare figma-mcp-0to1 sub-agent routing targets; improves discoverability of install-auth, tool-function-catalog, canvas-creation-playbook, and troubleshooting-ops delegation modes; affects figma-mcp-0to1 manifest metadata"
+  version: "1.0.2"
+  changelog: "Refreshed Figma MCP tools, commands, permissions, Make resources, and agent-support notes against current Figma coverage; improves setup accuracy and 0-to-1 workflow reliability; affects figma-mcp-0to1 docs, references, assets, and metadata"
   auto-invoke: "Installing, configuring, or using Figma MCP from setup through first canvas creation"
   allowed-tools:
     - "Read"
@@ -30,6 +30,7 @@ Use this skill when:
 - You need a reliable path from connection to first successful canvas output.
 - You need to choose the right Figma MCP function for a task.
 - You need operational recovery for permission, auth, tool-loading, or rate-limit failures.
+- You need to understand which skilly-hand agents overlap with Figma-supported MCP clients.
 
 Do not use this skill for:
 
@@ -57,14 +58,17 @@ Choose subskills by intent:
 1. Set up server transport and authentication.
 2. Verify connectivity with a low-risk call (`whoami` on remote, or a read tool).
 3. Select the smallest tool that solves the immediate task.
-4. Run creation in short, validated steps (avoid large one-shot requests).
-5. If anything fails, use troubleshooting flow before retrying.
+4. For writes, inspect existing file/design-system context before creating new content.
+5. Run creation in short, validated steps (avoid large one-shot requests).
+6. If anything fails, use troubleshooting flow before retrying.
 
 ---
 
 ## Core Rules
 
 - Prefer remote server for broadest feature coverage and write workflows.
+- Treat official Figma MCP docs as the source of truth for official tools, supported clients, permissions, and limits.
+- Keep client-specific helpers separate from official Figma MCP tools.
 - Treat write actions as staged operations, not a single large operation.
 - Use link-based node targeting for reliable design-context extraction.
 - Keep a clear distinction between read context tools and write/canvas tools.
@@ -72,6 +76,18 @@ Choose subskills by intent:
 
 ---
 
+## Agent Coverage
+
+Figma MCP support and skilly-hand installation support are related but not identical:
+
+| Coverage | Agents or Clients | Guidance |
+| --- | --- | --- |
+| Figma-supported and skilly-hand-supported | `codex`, `claude`, `cursor`, `copilot` | Include concrete setup paths in this skill. |
+| Figma-supported but not skilly-hand-native | VS Code, Warp, Augment, Factory, Firebender | Mention as Figma-supported clients, but do not add skilly-hand install assumptions. |
+| skilly-hand-supported but not source-backed in current Figma docs | `gemini`, `antigravity`, `windsurf`, `trae` | Keep broad `agentSupport`; document that Figma-specific setup may require client documentation or manual MCP config. |
+
+---
+
 ## Key References
 
 - Full function matrix: [references/official-tools-matrix.md](references/official-tools-matrix.md)
@@ -86,6 +102,21 @@ Choose subskills by intent:
 # Codex CLI (manual remote setup)
 codex mcp add figma --url https://mcp.figma.com/mcp
 
+# Claude Code plugin setup
+claude plugin install figma@claude-plugins-official
+
+# Claude Code manual remote setup
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+
+# Claude Code manual remote setup, user scope
+claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
+
+# Claude Code manual desktop setup
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+
+# Cursor plugin setup
+/add-plugin figma
+
 # Verify catalog integrity in this repository
 npm run catalog:check
 ```

package/catalog/skills/figma-mcp-0to1/agents/canvas-creation-playbook.md

@@ -7,14 +7,17 @@ Deliver a first successful Figma canvas result with low risk and clear verificat
 ## Safe 0-to-1 Workflow
 
 1. **Create or choose file context**
-- New file path: call `create_new_file`.
+- New file path: run `whoami` if needed to obtain a plan/team context, then call `create_new_file`.
 - Existing file path: confirm URL/node target and permissions.
+- Live web UI path: use `generate_figma_design` to capture to a new file, existing file, or clipboard.
+- Make path: use MCP resources from a Figma Make link to fetch project/file context before implementation.
 
 2. **Verify identity and access**
 - Run `whoami` (remote) to confirm account/plan.
 - If access mismatch appears, stop and fix permissions first.
 
 3. **Read before write**
+- Use `get_libraries` if the Codex Figma plugin exposes it and library scope matters.
 - Call `search_design_system` to reuse components/variables.
 - Optionally call `get_metadata` for structure baseline.
 
@@ -23,6 +26,7 @@ Deliver a first successful Figma canvas result with low risk and clear verificat
 - Create one frame.
 - Add one text node.
 - Apply one style/token decision.
+- For FigJam, create or update one small board object such as a sticky, section, connector, or shape.
 
 5. **Validate state**
 - Inspect with `get_metadata` or `get_screenshot`.
@@ -36,19 +40,27 @@ Deliver a first successful Figma canvas result with low risk and clear verificat
 
 ### Diagram-first flow (FigJam)
 
-1. `create_new_file` (FigJam)
-2. `generate_diagram` from plain-language workflow description
-3. Validate diagram structure and labels
+1. Call `generate_diagram` from plain-language workflow description or Mermaid syntax.
+2. Let `generate_diagram` create a new FigJam file, or provide an existing FigJam file key.
+3. Validate diagram structure and labels.
 
 ### Code-to-canvas flow
 
-1. Ask client to start local app capture workflow
-2. Capture screen/element states to Figma
-3. Open generated file and validate generated layers
-4. Follow up with `use_figma` for cleanup/polish
+1. Ask client to start local app capture workflow.
+2. Use `generate_figma_design` to capture screen/element states to a new file, existing file, or clipboard.
+3. Open generated file and validate generated layers.
+4. Follow up with `use_figma` for cleanup/polish.
+
+### Make-to-code context flow
+
+1. Provide a valid Figma Make link.
+2. Use MCP resources to list available project files.
+3. Fetch only the files needed for the task.
+4. Implement or refine the production code using that Make context.
 
 ## Guardrails
 
 - Do not run large multi-section writes as the first operation.
 - Always return to read/verify tools after each write step.
 - If a write fails, use troubleshooting flow before retrying.
+- Do not call `create_new_file` before `generate_diagram`; diagrams can create their own FigJam file.

package/catalog/skills/figma-mcp-0to1/agents/install-auth.md

@@ -8,8 +8,8 @@ Get Figma MCP connected and authenticated, with a verified first tool call.
 
 | Mode | Endpoint | Recommended | Notes |
 | --- | --- | --- | --- |
-| Remote | `https://mcp.figma.com/mcp` | Yes | Broadest features, including write-to-canvas workflows. |
-| Desktop | `http://127.0.0.1:3845/mcp` | Only for special org/enterprise needs | Requires Figma desktop app + Dev Mode desktop MCP toggle. |
+| Remote | `https://mcp.figma.com/mcp` | Yes | Broadest feature coverage, including write-to-canvas, code-to-canvas, diagrams, and file creation. |
+| Desktop | `http://127.0.0.1:3845/mcp` | Only for local selection-based or special org needs | Requires Figma desktop app + Dev Mode desktop MCP toggle; narrower workflow coverage. |
 
 ## Codex Setup
 
@@ -26,15 +26,29 @@ codex mcp add figma --url https://mcp.figma.com/mcp
 
 When prompted, authenticate the server.
 
-## Other Common Clients (manual patterns)
+## Other Supported Client Paths
 
+Use concrete setup paths for agents that are both Figma-supported and skilly-hand-supported:
+
+- Claude Code plugin: `claude plugin install figma@claude-plugins-official`
+- Claude Code manual remote: `claude mcp add --transport http figma https://mcp.figma.com/mcp`
+- Claude Code user-scope remote: `claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp`
+- Claude Code manual desktop: `claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp`
+- Cursor plugin: `/add-plugin figma`
+- Cursor manual: add the remote or desktop endpoint in MCP settings.
+- Copilot: use the VS Code MCP route and enable GitHub Copilot in the client.
 - VS Code: add HTTP MCP server in `mcp.json` using the remote endpoint.
-- Cursor: add MCP server in MCP settings or use its Figma plugin flow.
-- Claude Code: `claude mcp add --transport http figma https://mcp.figma.com/mcp`.
-- Gemini CLI: install Figma extension from `figma/mcp-server-guide`, then run auth command in CLI.
 
 See exact snippets in [../assets/client-config-snippets.md](../assets/client-config-snippets.md).
 
+## Agent Coverage Notes
+
+| Coverage | Agents or Clients | Guidance |
+| --- | --- | --- |
+| Figma-supported and skilly-hand-supported | `codex`, `claude`, `cursor`, `copilot` | Use the commands and setup paths above. |
+| Figma-supported but not skilly-hand-native | VS Code, Warp, Augment, Factory, Firebender | Follow Figma/client setup docs; do not assume skilly-hand skill install paths. |
+| skilly-hand-supported but not source-backed in current Figma docs | `gemini`, `antigravity`, `windsurf`, `trae` | Keep install support, but verify Figma MCP setup through that client's docs or manual MCP config. |
+
 ## Verification Checklist
 
 1. Confirm server appears in client MCP list.
@@ -42,13 +56,16 @@ See exact snippets in [../assets/client-config-snippets.md](../assets/client-con
 - Remote: `whoami` (recommended)
 - Desktop-only contexts: `get_metadata` or `get_design_context` on a known node
 3. Confirm the authenticated user has access to the target Figma file.
+4. For write workflows, confirm the authenticated seat can edit the target file.
 
 ## First Prompt After Setup
 
 - "Use Figma MCP `whoami` and show which account is authenticated."
 - "Use Figma MCP `get_design_context` for this node URL and summarize dimensions, layout, and variables."
+- "Using this Figma file URL, inspect the current libraries before creating anything new."
 
 ## Notes
 
 - If tools do not appear, restart MCP client session and retry authentication.
 - If permissions fail, verify file sharing and plan seat alignment before retry.
+- If a client does not expose an official tool, check the active tool list before changing the workflow.

package/catalog/skills/figma-mcp-0to1/agents/tool-function-catalog.md

@@ -7,20 +7,23 @@ Pick the smallest correct Figma MCP function for the task, with predictable inpu
 ## Start Here
 
 1. Read [../references/official-tools-matrix.md](../references/official-tools-matrix.md).
-2. Identify whether task is read, write, design-system search, code-connect, or diagram.
+2. Identify whether task is read, write, design-system search, code-connect, diagram, live UI capture, or Make resource context.
 3. Prefer read-first calls before write calls on unknown files.
 
 ## Selection Rules
 
 - Need full style/layout context for implementation: `get_design_context`.
+- Need Figma Make project/file context: use MCP resources if the client supports resources.
 - Output too large or structure-first pass: `get_metadata` first, then targeted `get_design_context`.
 - Need variables/tokens only: `get_variable_defs`.
 - Need visual reference: `get_screenshot`.
 - Need FigJam extraction: `get_figjam`.
+- Need library discovery in Codex before a scoped search: `get_libraries` if the Codex Figma plugin exposes it.
 - Need design-system discovery before creating: `search_design_system`.
-- Need to write/create/update content: `use_figma` (remote write workflows).
-- Need new blank file: `create_new_file`.
-- Need Mermaid-to-FigJam: `generate_diagram`.
+- Need to write/create/update Figma Design or FigJam content: `use_figma` (remote write workflow; use `figma-use` skill when available).
+- Need first-time live web UI capture: `generate_figma_design`.
+- Need new blank file: `create_new_file` (requires plan/team context such as `planKey` in some clients).
+- Need Mermaid-to-FigJam: `generate_diagram` (creates its own FigJam file unless an existing FigJam file key is provided).
 - Need code-connect lookup/update: `get_code_connect_map`, `add_code_connect_map`, suggestion/confirm functions.
 
 ## Prompting Pattern
@@ -28,11 +31,15 @@ Pick the smallest correct Figma MCP function for the task, with predictable inpu
 Use direct tool-trigger language when selection is ambiguous:
 
 - "Use Figma MCP `get_metadata` first, then `get_design_context` only for the selected child nodes."
+- "Use `get_libraries` if available, then use Figma MCP `search_design_system` for the selected library."
 - "Use Figma MCP `search_design_system` before creating any new component."
+- "Use Figma MCP `generate_figma_design` to capture this live web UI to a new Figma file."
 - "Use Figma MCP `create_new_file`, then `use_figma` to add a first frame and typography style."
+- "Use MCP resources from this Figma Make link and fetch only the files needed for implementation."
 
 ## Remote/Desktop Caveats
 
 - Remote-only flags are tracked in the matrix; confirm availability before relying on those functions.
-- Write-to-canvas flows are remote-first in current official guidance.
+- Write-to-canvas flows are remote-only in current official guidance.
 - Desktop mode is valid for local selection-based extraction, but with narrower workflow coverage.
+- Selection-based prompting works with the desktop server; remote workflows should use Figma file or node links.

package/catalog/skills/figma-mcp-0to1/agents/troubleshooting-ops.md

@@ -14,6 +14,8 @@ Failure observed?
      -> Verify link format, run whoami, confirm seat/plan and file access
   -> Rate-limit behavior
      -> Reduce read call volume, stage calls, wait/backoff, upgrade seat/plan if needed
+  -> Missing expected tool
+     -> Compare active client tools with official matrix, then choose a supported fallback
   -> Write failure
      -> Stop retries, inspect state with read tools, fix cause, retry scoped step
 ```
@@ -35,15 +37,27 @@ Failure observed?
 ### Rate limiting
 
 - Read-heavy calls are rate-limited by plan/seat.
+- Starter plan or View/Collab seats are limited to low monthly usage.
+- Dev/Full seats on Professional or Organization plans have higher daily usage.
+- Enterprise Dev/Full seats have the highest documented daily usage.
+- Officially documented exempt tools include `add_code_connect_map`, `generate_figma_design`, and `whoami`.
 - Use smaller selections and fewer repeated reads.
 - Prefer `get_metadata` preflight before broad `get_design_context`.
 - Batch intent into fewer, targeted calls.
 
+### Missing expected tools
+
+- Official Figma MCP tools may not be exposed by every client plugin surface.
+- Client-specific helpers, such as Codex `get_libraries`, are not official substitutes for every client.
+- Prefer a documented fallback rather than forcing an unavailable tool.
+
 ### Write step errors
 
 - Do not immediately retry the exact same large request.
 - Split into smaller write actions.
 - Verify partial outcomes using read tools before next step.
+- For `create_new_file`, ensure a plan/team context is available.
+- For `generate_diagram`, do not pre-create a blank FigJam file unless adding to an existing file is the explicit goal.
 
 ## Scoped Retry Pattern
 

package/catalog/skills/figma-mcp-0to1/assets/client-config-snippets.md

@@ -14,6 +14,37 @@
 codex mcp add figma --url https://mcp.figma.com/mcp
 ```
 
+## Codex App
+
+Use the Figma plugin/app install path in Codex when available, then complete the OAuth authentication flow.
+
+## Claude Code Plugin
+
+```bash
+claude plugin install figma@claude-plugins-official
+```
+
+## Claude Code (manual remote)
+
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+claude mcp list
+```
+
+## Claude Code (manual remote, user scope)
+
+```bash
+claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
+claude mcp list
+```
+
+## Claude Code (manual desktop)
+
+```bash
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+claude mcp list
+```
+
 ## VS Code `mcp.json` (remote)
 
 ```json
@@ -53,24 +84,38 @@ codex mcp add figma --url https://mcp.figma.com/mcp
 }
 ```
 
-## Claude Code (manual remote)
+## Cursor Plugin
 
 ```bash
-claude mcp add --transport http figma https://mcp.figma.com/mcp
-claude mcp list
+/add-plugin figma
 ```
 
-## Claude Code (manual desktop)
+## Cursor MCP config (desktop)
 
-```bash
-claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
-claude mcp list
+```json
+{
+  "mcpServers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
 ```
 
-## Gemini CLI
+## Other Desktop MCP Config
 
-```bash
-gemini extensions install https://github.com/figma/mcp-server-guide
-# then inside gemini CLI:
-# /mcp auth figma
+```json
+{
+  "mcpServers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
 ```
+
+## Agent Coverage Notes
+
+- Figma-supported and skilly-hand-supported: `codex`, `claude`, `cursor`, `copilot`.
+- Figma-supported but not skilly-hand-native: VS Code, Warp, Augment, Factory, Firebender.
+- skilly-hand-supported but not source-backed in current Figma docs: `gemini`, `antigravity`, `windsurf`, `trae`.

package/catalog/skills/figma-mcp-0to1/assets/prompt-recipes.md

@@ -4,31 +4,55 @@
 
 - "Set up Figma MCP remote server and verify with `whoami`."
 - "Use Figma MCP `whoami` and tell me which account and plans are active."
+- "Check whether this client exposes the Figma MCP tools I need before starting."
 
 ## Read Context
 
 - "Use `get_design_context` for this node URL and return layout, spacing, typography, and variables."
 - "Use `get_metadata` first, then call `get_design_context` only for the button and header nodes."
 - "Use `get_variable_defs` for this node and list token names with resolved values."
+- "Use `get_screenshot` for this node and compare it against the generated implementation."
+- "Use Figma MCP resources from this Figma Make link and fetch only the files needed for this component."
 
 ## Design-System and Code Connect
 
+- "Use `get_libraries` if available, then search only the relevant design libraries."
 - "Use `search_design_system` to find an existing card and button component before creating anything new."
+- "Use `search_design_system` to find primary color, typography, and spacing variables."
 - "Use `get_code_connect_map` for this node and show mapped source locations."
 - "Use `add_code_connect_map` to map this Figma node to my component path."
+- "Use `get_code_connect_suggestions`, then confirm mappings with `send_code_connect_mappings` if the suggestions are correct."
 
 ## First Canvas Creation
 
+- "Use `whoami` to choose the right plan, then use `create_new_file` to create a new design file named 'MCP First Canvas'."
 - "Use `create_new_file` to create a new design file named 'MCP First Canvas'."
 - "Use `use_figma` to create one frame, add one title text layer, and apply auto layout spacing."
 - "After the write, use `get_screenshot` to verify the result."
+- "Before writing, inspect the file and use `search_design_system` for existing components or variables."
+
+## Live UI Capture
+
+- "Start my local app and use `generate_figma_design` to capture the current screen into a new Figma file."
+- "Use `generate_figma_design` to capture this URL into the existing Figma file."
+- "Use `generate_figma_design` to capture this page to my clipboard."
 
 ## FigJam Flows
 
 - "Use `create_new_file` to create a new FigJam board for architecture planning."
 - "Use `generate_diagram` to create a sequence diagram for login and checkout flow."
+- "Use `generate_diagram` to add an ERD to this existing FigJam file."
+- "Use `use_figma` to organize this FigJam board into sections with stickies and connectors."
+- "Use `use_figma` to update this architecture diagram with a new service."
+
+## Agent Coverage
+
+- "For this agent, tell me whether Figma officially supports its MCP setup path and which command/config I should use."
+- "Compare this client's active Figma tools against the official Figma MCP matrix before choosing a workflow."
 
 ## Troubleshooting
 
 - "I got a permission error. Use `whoami` and tell me what to check next."
 - "I am rate-limited. Switch to a staged workflow with fewer `get_design_context` calls."
+- "This client does not expose `get_screenshot`. Choose the closest supported verification path."
+- "My `create_new_file` call failed. Check whether a plan key or team context is missing."

package/catalog/skills/figma-mcp-0to1/manifest.json

@@ -10,10 +10,10 @@
   "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.0.1",
-    "changelog": "Added allowed-modes metadata to declare figma-mcp-0to1 sub-agent routing targets; improves discoverability of install-auth, tool-function-catalog, canvas-creation-playbook, and troubleshooting-ops delegation modes; affects figma-mcp-0to1 manifest metadata",
+    "version": "1.0.2",
+    "changelog": "Refreshed Figma MCP tools, commands, permissions, Make resources, and agent-support notes against current Figma coverage; improves setup accuracy and 0-to-1 workflow reliability; affects figma-mcp-0to1 docs, references, assets, and metadata",
     "auto-invoke": "Installing, configuring, or using Figma MCP from setup through first canvas creation",
     "allowed-modes": [
       "install-auth",

package/catalog/skills/figma-mcp-0to1/references/official-tools-matrix.md

@@ -1,31 +1,56 @@
-# Official Figma MCP Tools Matrix (As of 2026-04-03)
+# Official Figma MCP Tools Matrix (As of 2026-05-01)
 
-This matrix tracks the official Figma MCP tool/function set in current Figma documentation.
+This matrix tracks the official Figma MCP tool/function set in current Figma documentation. Treat it as the source of truth for official tool names, supported file types, and remote-only status. Client-specific helpers are listed separately.
 
 ## Coverage Matrix
 
 | Tool | Primary Purpose | Typical Input | Supported File Types | Availability Notes |
 | --- | --- | --- | --- | --- |
-| `generate_figma_design` | Generate design layers from live web UI (code to canvas path) | URL/local app capture context | No file context required | Remote-only in official docs. |
-| `get_design_context` | Fetch rich design context for implementation | Figma URL or `fileKey` + `nodeId` | Figma Design | Read tool; use link-based node targeting. |
+| `generate_figma_design` | Generate editable design layers from live web UI | URL/local app capture context | Figma Design output | Remote-only; select clients only; can output to new file, existing file, or clipboard; exempt from standard read limits. |
+| `get_design_context` | Fetch rich design context for implementation | Figma URL or `fileKey` + `nodeId` | Figma Design, Figma Make | Read tool; remote server requires link-based node targeting; desktop can use selection-based prompts. |
 | `get_variable_defs` | Retrieve variable/token definitions | `fileKey` + `nodeId` | Figma Design | Best for token-only extraction. |
 | `get_code_connect_map` | Read existing Code Connect mappings | `fileKey` + `nodeId` | Figma Design | Use to inspect mapping before updates. |
 | `add_code_connect_map` | Add mapping from node to code component | `fileKey`, `nodeId`, source details | Figma Design | Write-style utility; exempt from read rate limits in docs. |
-| `get_screenshot` | Render node screenshot for visual verification | `fileKey` + `nodeId` | Figma Design | Useful verification after write steps. |
+| `get_screenshot` | Render node screenshot for visual verification | `fileKey` + `nodeId` | Figma Design, FigJam | Useful verification after write steps and for preserving visual fidelity. |
 | `create_design_system_rules` | Generate design-system rules prompt/scaffold | Framework/language context | No file context required | Use to enforce repeatable design-system workflows. |
 | `get_metadata` | Sparse XML structure (ids, names, hierarchy, bounds) | Selection or `fileKey` + `nodeId` | Figma Design | Preferred preflight for large contexts. |
 | `get_figjam` | Fetch FigJam metadata (and node visuals) | `fileKey` + `nodeId` | FigJam | FigJam-specific extraction. |
-| `generate_diagram` | Create FigJam diagram from Mermaid or natural language intent | Diagram description or Mermaid syntax | No file context required | Supports flowchart, gantt, state, sequence. |
+| `generate_diagram` | Create FigJam diagram from Mermaid or natural language intent | Diagram description or Mermaid syntax | No file context required | Remote-only; supports flowchart, gantt, state, sequence, architecture, and ERD workflows. |
 | `whoami` | Show authenticated Figma identity, plans, and seat types | None | No file context required | Remote-only in official docs; exempt from read rate limits. |
 | `get_code_connect_suggestions` | Suggest candidate node-to-code mappings | File context + repo context | Figma Design | Usually part of Code Connect workflows. |
 | `send_code_connect_mappings` | Confirm/persist mapping suggestions | Suggestions payload | Figma Design | Follow-up action after suggestion generation. |
-| `use_figma` | General-purpose write/edit/delete/inspect in Figma via Plugin API workflow | Task instructions and file context | Figma Design, FigJam | Write-to-canvas workflow path; remote-first guidance. |
-| `search_design_system` | Search libraries for components, variables, styles | Query text and optional type narrowing | Figma Design | Use before creating new artifacts. |
-| `create_new_file` | Create new blank Design or FigJam file | Name/type intent | No file context required | Good first step for 0-to-1 creation workflows. |
+| `use_figma` | General-purpose write/edit/delete/inspect via Plugin API workflow | Task instructions and file context | Figma Design, FigJam | Remote-only; default direct write/update path; best used with the `figma-use` skill when available. |
+| `search_design_system` | Search libraries for components, variables, styles | Query text and optional type narrowing | Figma Design | Remote-only; use before creating new artifacts when design-system reuse is relevant. |
+| `create_new_file` | Create new blank Design or FigJam file | File name, file type, plan context | No file context required | Remote-only; creates files in drafts or a project; requires plan/team context in some clients. |
+
+## Figma Make Resources
+
+Figma Make project context is exposed through MCP resources on clients that support MCP resources. Use a valid Figma Make link, let the client list available project files, and fetch only the files needed for the implementation task.
+
+## Codex Plugin Helpers
+
+The Codex Figma plugin may expose helper tools beyond the current official tools page. Keep these documented as client-specific helpers:
+
+| Helper | Purpose | Notes |
+| --- | --- | --- |
+| `get_libraries` | List libraries associated with a Figma file | Use before scoped `search_design_system`; not listed on the official Figma tools page as of this matrix date. |
+
+Some official Figma MCP tools may not be exposed by every client plugin surface. Prefer the active client's tool list over assumptions when executing.
+
+## Client and Agent Coverage
+
+| Coverage | Agents or Clients | Guidance |
+| --- | --- | --- |
+| Figma-supported and skilly-hand-supported | `codex`, `claude`, `cursor`, `copilot` | Include concrete setup paths and prompts in this skill. |
+| Figma-supported but not skilly-hand-native | VS Code, Warp, Augment, Factory, Firebender | Mention as Figma-supported clients; do not add skilly-hand install assumptions. |
+| skilly-hand-supported but not source-backed in current Figma docs | `gemini`, `antigravity`, `windsurf`, `trae` | Keep broad install support; advise manual MCP/client docs for Figma-specific setup. |
 
 ## Rate-Limit Notes (Official)
 
-- Read tools are subject to seat/plan limits.
+- Read tools are subject to seat/plan limits and per-minute limits.
+- Starter plan or View/Collab seats: up to 6 tool calls per month.
+- Professional or Organization with Dev/Full seat: up to 200 tool calls per day.
+- Enterprise with Dev/Full seat: up to 600 tool calls per day.
 - Officially documented exempt tools include:
 - `add_code_connect_map`
 - `generate_figma_design`
@@ -35,9 +60,11 @@ This matrix tracks the official Figma MCP tool/function set in current Figma doc
 
 1. Start with `whoami` when authentication or permissions are uncertain.
 2. Use `get_metadata` before `get_design_context` for large files.
-3. Use `search_design_system` before creating new components.
-4. Keep `use_figma` calls small and validate after each step.
-5. Use `get_screenshot` as final visual verification after edits.
+3. Use `get_libraries` where available, then `search_design_system` for scoped design-system reuse.
+4. Use `generate_figma_design` for first-time live web UI capture.
+5. Use `use_figma` for direct Figma Design or FigJam writes and updates.
+6. Keep `use_figma` calls small and validate after each step.
+7. Use `get_screenshot` as final visual verification after edits when available.
 
 ## Sources
 
@@ -45,5 +72,8 @@ This matrix tracks the official Figma MCP tool/function set in current Figma doc
 - https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/
 - https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
 - https://developers.figma.com/docs/figma-mcp-server/local-server-installation/
+- https://developers.figma.com/docs/figma-mcp-server/write-to-canvas/
+- https://developers.figma.com/docs/figma-mcp-server/code-to-canvas/
+- https://developers.figma.com/docs/figma-mcp-server/bringing-make-context-to-your-agent/
 - https://developers.figma.com/docs/figma-mcp-server/plans-access-and-permissions/
 - https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server

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.2",
+  "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.2",
+  "version": "0.26.0",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

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

package/packages/detectors/package.json

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