@skilly-hand/skilly-hand 0.10.0 → 0.10.3

package/CHANGELOG.md

@@ -16,6 +16,51 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.10.3] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.10.3)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.10.2] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.10.2)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.10.1] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.10.1)
+
+### Added
+- _None._
+
+### Changed
+- Removed the `AI Integrated Structures` subsection from `README.md` to keep assistant compatibility docs focused on current install targets.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.10.0] - 2026-04-04
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.10.0)
 

package/README.md

@@ -121,12 +121,6 @@ Skills are installed into `.skilly-hand/` with the correct format for each tool:
 | Windsurf | `.windsurf/skills/`, `AGENTS.md` |
 | TRAE | `.trae/skills/`, `AGENTS.md` |
 
-### AI Integrated Structures
-
-- Antigravity: rules at `~/.gemini/GEMINI.md` (global) and workspace `.agents/rules/` (with `.agent/rules/` backward support); skills at `.agents/skills/` or `~/.gemini/antigravity/skills/`; MCP config at `~/.gemini/antigravity/mcp_config.json`.
-- Windsurf: AGENTS-based directory scoping via `AGENTS.md`, rules in `.windsurf/rules/`, skills in `.windsurf/skills/` (plus `.agents/skills/` compatibility), MCP config at `~/.codeium/mcp_config.json`.
-- TRAE: project rules in `.trae/rules/` with `AGENTS.md` support, skills in `.trae/skills/` (optional `.agents/skills/` compatibility toggle), MCP project config via `.trae/mcp.json` and manual/marketplace management in-app.
-
 ---
 
 ## Project Structure

package/catalog/README.md

@@ -10,6 +10,7 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `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. | frontend, design, workflow, ui | all |
 | `life-guard` | 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 |
+| `react-guidelines` | Guide React code generation and review using latest stable React verification and modern framework best practices. | react, frontend, workflow, best-practices | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
 | `test-driven-development` | Guide implementation using the RED → GREEN → REFACTOR TDD cycle: write a failing test first, write the minimum code to pass, then refactor while tests stay green. | testing, workflow, quality, core | all |

package/catalog/catalog-index.json

@@ -5,6 +5,7 @@
   "figma-mcp-0to1",
   "frontend-design",
   "life-guard",
+  "react-guidelines",
   "skill-creator",
   "spec-driven-development",
   "test-driven-development",

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

@@ -0,0 +1,188 @@
+# React Guidelines
+
+## When to Use
+
+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.
+
+Do not use this skill for:
+
+- Non-React frontend stacks (Angular, Vue, Svelte, or framework-agnostic UI tasks).
+- Deep architecture decisions outside code artifact generation/review scope.
+- Pure test-strategy design unrelated to React implementation details.
+
+---
+
+## Routing Map
+
+Choose sub-agents by intent:
+
+| Intent | Sub-agent |
+| --- | --- |
+| 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) |
+
+---
+
+## Standard Execution Sequence
+
+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.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Latest Stable React Preflight (Mandatory)
+
+Before generating or changing React code:
+
+1. Check the latest stable React release:
+   `npm view react version`
+2. Check the project's installed or declared React version:
+   `npm ls react` or inspect `package.json`.
+3. Verify release alignment using official version documentation:
+   `https://react.dev/versions`
+4. If versions diverge, generate content for latest stable APIs and call out upgrade steps.
+
+Never hardcode a specific React major/minor as the default baseline.
+
+### Pattern 2: Modern React Defaults for New Code
+
+Use these defaults unless project constraints explicitly prevent them:
+
+| Area | Default |
+| --- | --- |
+| Component model | Function components with pure render logic |
+| State + derivation | `useState`/`useReducer` + derived values without redundant state |
+| Reuse | Composition and custom hooks over inheritance |
+| Boundaries | Apply `'use client'` or `'use server'` only where required |
+| Rendering patterns | Suspense-ready async boundaries where applicable |
+| Debug/profiling | StrictMode-safe behavior and optional Profiler instrumentation |
+
+### Pattern 3: Hook and Purity Guardrails
+
+- Follow Rules of Hooks consistently.
+- Keep Components and Hooks pure.
+- Avoid unnecessary Effects; prefer deriving values in render when possible.
+- 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).
+
+---
+
+## Decision Tree
+
+```text
+Is this a React project (react dependency present)?
+  NO  -> Do not apply this skill
+  YES -> Continue
+
+Is this a create/generate task?
+  YES -> Run latest stable preflight, then generate with modern defaults
+  NO  -> Continue
+
+Is this a refactor task?
+  YES -> Preserve behavior, migrate incrementally to modern React patterns
+  NO  -> Continue
+
+Is this a review task?
+  YES -> Validate latest-stable alignment + hook/purity checklist
+  NO  -> Apply the minimal React guidance needed for the request
+```
+
+---
+
+## Code Examples
+
+### Example 1: Pure Function Component with Derived State
+
+```tsx
+import { useMemo, useState } from "react";
+
+type CounterBadgeProps = {
+  label: string;
+};
+
+export function CounterBadge({ label }: CounterBadgeProps) {
+  const [count, setCount] = useState(0);
+  const isNonZero = useMemo(() => count > 0, [count]);
+
+  return (
+    <button type="button" onClick={() => setCount((value) => value + 1)}>
+      {label}: {count} {isNonZero ? "active" : "idle"}
+    </button>
+  );
+}
+```
+
+### Example 2: Server/Client Boundary Split
+
+```tsx
+// app/user-panel.tsx
+import { UserPanelClient } from "./user-panel-client";
+
+export default async function UserPanel() {
+  const user = await fetch("/api/user").then((r) => r.json());
+  return <UserPanelClient name={user.name} />;
+}
+
+// app/user-panel-client.tsx
+"use client";
+
+export function UserPanelClient({ name }: { name: string }) {
+  return <p>Hello, {name}</p>;
+}
+```
+
+---
+
+## Review Checklist
+
+- Latest stable React preflight was completed before code generation/refactor.
+- New artifacts use function-first, composition-first patterns.
+- 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.
+
+---
+
+## Commands
+
+```bash
+# Latest stable React version
+npm view react version
+
+# Workspace React version
+npm ls react
+
+# Build catalog index
+npm run build
+
+# Sync catalog README table
+npm run catalog:sync
+
+# Validate catalog manifests and files
+npm run catalog:check
+```
+
+---
+
+## Resources
+
+- React reference: https://react.dev/reference/react
+- React Hooks reference: https://react.dev/reference/react/hooks
+- React Components reference: https://react.dev/reference/react/components
+- React APIs reference: https://react.dev/reference/react/apis
+- React Server Components directives: https://react.dev/reference/rsc/directives
+- React versions: https://react.dev/versions
+- Rules of Hooks: https://react.dev/reference/rules/rules-of-hooks
+- Components and Hooks must be pure: https://react.dev/reference/rules/components-and-hooks-must-be-pure
+- Suspense: https://react.dev/reference/react/Suspense
+- StrictMode: https://react.dev/reference/react/StrictMode
+- Fragment: https://react.dev/reference/react/Fragment
+- Profiler: https://react.dev/reference/react/Profiler

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

@@ -0,0 +1,88 @@
+# React Component Creator
+
+## When to Use
+
+Use this sub-agent when:
+
+- Creating a new React component.
+- Refactoring an existing React component to modern patterns.
+- Reviewing component implementation details and composition patterns.
+
+Do not use this sub-agent for:
+
+- Framework-agnostic architecture decisions.
+- Test-only tasks (use `react-tester`).
+- Non-React frameworks.
+
+---
+
+## Core Rules
+
+- Prefer function components and composition-first design.
+- Keep render logic pure and deterministic.
+- Keep state minimal; derive values from props/state instead of duplicating state.
+- Use custom hooks to encapsulate reusable stateful behavior.
+- Follow Rules of Hooks in all code paths.
+- Use `'use client'` only for interactive/client-only modules; keep server components free of client-only hooks.
+- For interactive elements, include keyboard and ARIA semantics.
+
+---
+
+## Template Snippets
+
+### Minimal Pure Function Component
+
+```tsx
+type BadgeProps = {
+  label: string;
+};
+
+export function Badge({ label }: BadgeProps) {
+  return <span>{label}</span>;
+}
+```
+
+### Composition + Custom Hook
+
+```tsx
+import { useState } from "react";
+
+function useToggle(initial = false) {
+  const [on, setOn] = useState(initial);
+  return { on, toggle: () => setOn((value) => !value) };
+}
+
+export function ToggleButton() {
+  const { on, toggle } = useToggle();
+  return (
+    <button type="button" aria-pressed={on} onClick={toggle}>
+      {on ? "On" : "Off"}
+    </button>
+  );
+}
+```
+
+### Suspense Boundary
+
+```tsx
+import { Suspense } from "react";
+
+export function ProfileSection() {
+  return (
+    <Suspense fallback={<p>Loading profile...</p>}>
+      <ProfileContent />
+    </Suspense>
+  );
+}
+```
+
+---
+
+## Review Checklist
+
+- Component is function-based and render-pure.
+- State is minimal and colocated; derived values are not redundantly stored.
+- Hook calls follow Rules of Hooks.
+- Composition is preferred over inheritance or over-abstraction.
+- Client/server boundary directives are correctly scoped.
+- Accessibility semantics are present for interactive controls.

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

@@ -0,0 +1,111 @@
+# React Tester
+
+## When to Use
+
+Use this sub-agent when:
+
+- Adding or updating React component or hook tests.
+- Reviewing React tests for correctness and modern usage.
+- Choosing test patterns for async rendering, Suspense, and transitions.
+
+Do not use this sub-agent for:
+
+- Component implementation guidance without tests (use `component-creator`).
+- Framework-agnostic testing standards not tied to React behavior.
+
+---
+
+## Runner Policy
+
+- Default: Use the repository's existing configured runner and testing library.
+- Do not introduce test-runner migration inside unrelated feature tasks.
+- Keep assertions focused on user-visible behavior and public contracts.
+
+---
+
+## Core Testing Patterns
+
+- Ensure all stateful updates and async UI flows are wrapped in React-safe test flows (`act` semantics are respected by the testing setup).
+- Prefer user-observable assertions over implementation details.
+- Test Suspense fallbacks and resolved UI states when async boundaries exist.
+- Test transitions and deferred updates based on visible outcomes.
+- Keep mocks narrow and explicit at integration boundaries.
+
+---
+
+## Command Matrix
+
+| Scenario | Preferred Command | Fallback |
+| --- | --- | --- |
+| Run all tests | Project test command (for example `npm test`) | Workspace equivalent |
+| Watch mode | Project watch command | Workspace equivalent |
+| Coverage | Project coverage command | Workspace equivalent |
+| Single suite/file | Project targeted test command | Workspace equivalent |
+
+Always align commands with the workspace's existing test setup.
+
+---
+
+## Decision Tree
+
+```text
+Is this a component behavior test?
+  YES -> Assert rendered output, interactions, and accessibility semantics
+  NO  -> Continue
+
+Is this a custom hook test?
+  YES -> Test observable state transitions and returned contracts
+  NO  -> Continue
+
+Is behavior async or Suspense-based?
+  YES -> Assert fallback state and resolved state deterministically
+  NO  -> Continue
+
+Does behavior involve transitions/deferred rendering?
+  YES -> Assert user-visible final state, not internal scheduling details
+  NO  -> Use direct synchronous assertions
+```
+
+---
+
+## Test Snippets
+
+### Component Interaction Test
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ToggleButton } from "./toggle-button";
+
+it("toggles pressed state", async () => {
+  const user = userEvent.setup();
+  render(<ToggleButton />);
+
+  const button = screen.getByRole("button", { name: "Off" });
+  await user.click(button);
+
+  expect(screen.getByRole("button", { name: "On" })).toHaveAttribute("aria-pressed", "true");
+});
+```
+
+### Suspense Fallback Test
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { ProfileSection } from "./profile-section";
+
+it("shows fallback before async content resolves", () => {
+  render(<ProfileSection />);
+  expect(screen.getByText("Loading profile...")).toBeInTheDocument();
+});
+```
+
+---
+
+## Review Checklist
+
+- Tests respect existing runner/library configuration.
+- `act`-safe patterns are preserved for stateful and async updates.
+- Assertions validate user-visible behavior and contracts.
+- Suspense/transition scenarios are tested where relevant.
+- Mocks are limited to necessary boundaries.

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

@@ -0,0 +1,41 @@
+{
+  "id": "react-guidelines",
+  "title": "React Guidelines",
+  "description": "Guide React code generation and review using latest stable React verification and modern framework best practices.",
+  "portable": true,
+  "tags": ["react", "frontend", "workflow", "best-practices"],
+  "detectors": ["react"],
+  "detectionTriggers": ["auto"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-04",
+    "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",
+    "allowed-modes": [
+      "component-creator",
+      "react-tester"
+    ],
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "WebFetch",
+      "WebSearch",
+      "Task",
+      "SubAgent"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "agents/component-creator.md", "kind": "instruction" },
+    { "path": "agents/react-tester.md", "kind": "instruction" }
+  ],
+  "dependencies": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.10.0",
+  "version": "0.10.3",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {