{"skill":{"slug":"copilotkit-react","displayName":"CopilotKit React Best Practices","summary":"CopilotKit React best practices for agentic applications. Use when writing, reviewing, or refactoring React code that uses CopilotKit hooks (useAgent, useFro...","description":"---\nname: copilotkit-react-patterns\ndescription: CopilotKit React best practices for agentic applications. Use when writing, reviewing, or refactoring React code that uses CopilotKit hooks (useAgent, useFrontendTool, useRenderTool, useCopilotAction, useCopilotReadable), providers (CopilotKit), or chat UI components (CopilotChat, CopilotSidebar, CopilotPopup). Triggers on tasks involving agent integration, tool rendering, shared state, or generative UI in React.\nlicense: MIT\nmetadata:\n  author: copilotkit\n  version: \"2.0.0\"\n---\n\n# CopilotKit React Patterns\n\nBest practices for building agentic React applications with CopilotKit. Contains 25 rules across 6 categories, prioritized by impact to guide code generation and refactoring. Covers both v1 (`@copilotkit/react-core`) and v2 (`@copilotkit/react-core/v2`) APIs.\n\n## When to Apply\n\nReference these guidelines when:\n- Setting up `CopilotKit` provider in a React application\n- Using agent hooks (useAgent, useFrontendTool, useCopilotAction)\n- Rendering tool calls or custom messages from agents\n- Managing shared state between UI and agents via useCopilotReadable or useCoAgent\n- Building chat interfaces with CopilotChat, CopilotSidebar, or CopilotPopup\n- Configuring suggestions for proactive agent assistance\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | Provider Setup | CRITICAL | `provider-` |\n| 2 | Agent Hooks | HIGH | `agent-` |\n| 3 | Tool Rendering | HIGH | `tool-` |\n| 4 | Context & State | MEDIUM | `state-` |\n| 5 | Chat UI | MEDIUM | `ui-` |\n| 6 | Suggestions | LOW | `suggestions-` |\n\n## Quick Reference\n\n### 1. Provider Setup (CRITICAL)\n\n- `provider-runtime-url` - Always configure runtimeUrl to connect to your agent backend\n- `provider-single-endpoint` - Configure the agent prop for CoAgent routing\n- `provider-nested-providers` - Scope agent configurations with nested CopilotKit providers\n- `provider-tool-registration` - Register tools via hooks inside provider, not as props when possible\n\n### 2. Agent Hooks (HIGH)\n\n- `agent-use-agent-updates` - Specify update subscriptions to avoid unnecessary re-renders\n- `agent-agent-id` - Always pass agentId when running multiple agents\n- `agent-context-description` - Write descriptive context values for useCopilotReadable\n- `agent-frontend-tool-deps` - Declare dependency arrays for useFrontendTool\n- `agent-stable-tool-handlers` - Use useCallback for tool handler functions\n\n### 3. Tool Rendering (HIGH)\n\n- `tool-typed-args` - Define Zod schemas for useRenderTool parameters (v2)\n- `tool-status-handling` - Handle all three tool call statuses (inProgress, executing, complete)\n- `tool-wildcard-fallback` - Register a wildcard renderer as fallback for unknown tools\n- `tool-render-vs-frontend` - Use useRenderTool for display-only, useFrontendTool for side effects\n- `tool-component-hook` - Use useFrontendTool render prop for simple component rendering\n\n### 4. Context & State (MEDIUM)\n\n- `state-minimal-context` - Provide only relevant context to agents, not entire app state\n- `state-structured-values` - Use structured objects in useCopilotReadable, not serialized strings\n- `state-context-granularity` - Split context into multiple useCopilotReadable calls by domain\n- `state-avoid-stale-closures` - Use functional state updates in tool handlers\n\n### 5. Chat UI (MEDIUM)\n\n- `ui-chat-layout` - Choose CopilotSidebar for persistent chat, CopilotPopup for on-demand\n- `ui-custom-labels` - Always customize labels for your domain instead of defaults\n- `ui-welcome-screen` - Provide a welcome screen with suggested prompts\n- `ui-input-mode` - Use appropriate inputMode for your use case\n\n### 6. Suggestions (LOW)\n\n- `suggestions-configure` - Use useConfigureSuggestions (v2) or useCopilotChatSuggestions (v1)\n- `suggestions-context-driven` - Provide rich context so suggestions are relevant\n- `suggestions-loading-state` - Handle suggestion loading states via useSuggestions (v2)\n\n## How to Use\n\nRead individual rule files for detailed explanations and code examples:\n\n```\nrules/provider-runtime-url.md\nrules/agent-use-agent-updates.md\nrules/tool-typed-args.md\n```\n\nEach rule file contains:\n- Brief explanation of why it matters\n- Incorrect code example with explanation\n- Correct code example with explanation\n- Additional context and references\n\n## Full Compiled Document\n\nFor the complete guide with all rules expanded: `AGENTS.md`\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":1103,"installsAllTime":42,"installsCurrent":1,"stars":1,"versions":2},"createdAt":1771814241556,"updatedAt":1778491612653},"latestVersion":{"version":"1.0.1","createdAt":1772171186979,"changelog":"**CopilotKit React Patterns 2.0.0 – Major update for v2 API support**\n\n- Expanded guidance to cover both v1 (`@copilotkit/react-core`) and v2 (`@copilotkit/react-core/v2`) APIs.\n- Updated provider setup and rules for the new `CopilotKit` provider and `CoAgent` routing.\n- Revised agent/state rules to reflect new hooks (`useCopilotAction`, `useCopilotReadable`) and best practices.\n- Adjusted tool integration advice for v2 API patterns (including Zod schemas and new render prop usage).\n- Added version-specific suggestions handling and clarified API differences in recommendations.","license":null},"metadata":null,"owner":{"handle":"generaljerel","userId":"s17etndyykvrgrbc8gk53c7zpd884hca","displayName":"Jerel","image":"https://avatars.githubusercontent.com/u/85066839?v=4"},"moderation":null}