CopilotKit React Best Practices

CopilotKit React best practices for agentic applications. Use when writing, reviewing, or refactoring React code that uses CopilotKit hooks (useAgent, useFro...

Security Scan

The files and runtime instructions match the stated purpose (React best-practice guidance for CopilotKit); nothing requested or installed is disproportionate or unrelated.

Purpose & Capability

The skill's name/description (CopilotKit React best practices) align with the included rule files, README, and AGENTS.md. All files are documentation and examples for CopilotKit hooks/components; there are no unrelated credentials, binaries, or install steps requested.

Instruction Scope

SKILL.md and rule files provide coding guidelines and code examples only. They do not instruct the agent to read arbitrary system files, access unrelated environment variables, or send data to hidden endpoints. Example usage includes runtimeUrl/publicApiKey placeholders, but those are documented examples for legitimate configuration rather than secret-exfiltration instructions.

Install Mechanism

This is an instruction-only skill with no install spec and no code to execute. No downloads, installers, or third-party package installs are defined in the manifest.

Credentials

The skill declares no required environment variables, binaries, or config paths. Example snippets reference runtimeUrl and publicApiKey as legitimate configuration options for CopilotKit, but the skill does not demand secrets or unrelated credentials.

Persistence & Privilege

Flags show always:false and normal autonomous invocation allowed. The skill does not request permanent presence or modify other skills or system-wide settings. Its scope is documentation and guidance.

Assessment

This skill is documentation and examples for CopilotKit React usage and appears internally consistent. Before installing or using rules from it: 1) Verify the source or repository/trust of the author (metadata shows 'CopilotKit' but homepage/source is unknown). 2) When following the examples, ensure runtimeUrl/publicApiKey point to a trusted runtime/backend—do not paste production secrets into example snippets. 3) Be mindful that applying the guidance (e.g., sending app state via useCopilotReadable) may cause your app to transmit sensitive data to your agent backend; follow the skill's own advice to provide only relevant context. 4) If you need stronger assurance, obtain the original upstream docs/repo (links in metadata.json) and compare versions.

CopilotKit React Patterns

Best 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.

When to Apply

Reference these guidelines when:

• Setting up CopilotKit provider in a React application
• Using agent hooks (useAgent, useFrontendTool, useCopilotAction)
• Rendering tool calls or custom messages from agents
• Managing shared state between UI and agents via useCopilotReadable or useCoAgent
• Building chat interfaces with CopilotChat, CopilotSidebar, or CopilotPopup
• Configuring suggestions for proactive agent assistance

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Provider Setup	CRITICAL	provider-
2	Agent Hooks	HIGH	agent-
3	Tool Rendering	HIGH	tool-
4	Context & State	MEDIUM	state-
5	Chat UI	MEDIUM	ui-
6	Suggestions	LOW	suggestions-

Quick Reference

1. Provider Setup (CRITICAL)

• provider-runtime-url - Always configure runtimeUrl to connect to your agent backend
• provider-single-endpoint - Configure the agent prop for CoAgent routing
• provider-nested-providers - Scope agent configurations with nested CopilotKit providers
• provider-tool-registration - Register tools via hooks inside provider, not as props when possible

2. Agent Hooks (HIGH)

• agent-use-agent-updates - Specify update subscriptions to avoid unnecessary re-renders
• agent-agent-id - Always pass agentId when running multiple agents
• agent-context-description - Write descriptive context values for useCopilotReadable
• agent-frontend-tool-deps - Declare dependency arrays for useFrontendTool
• agent-stable-tool-handlers - Use useCallback for tool handler functions

3. Tool Rendering (HIGH)

• tool-typed-args - Define Zod schemas for useRenderTool parameters (v2)
• tool-status-handling - Handle all three tool call statuses (inProgress, executing, complete)
• tool-wildcard-fallback - Register a wildcard renderer as fallback for unknown tools
• tool-render-vs-frontend - Use useRenderTool for display-only, useFrontendTool for side effects
• tool-component-hook - Use useFrontendTool render prop for simple component rendering

4. Context & State (MEDIUM)

• state-minimal-context - Provide only relevant context to agents, not entire app state
• state-structured-values - Use structured objects in useCopilotReadable, not serialized strings
• state-context-granularity - Split context into multiple useCopilotReadable calls by domain
• state-avoid-stale-closures - Use functional state updates in tool handlers

5. Chat UI (MEDIUM)

• ui-chat-layout - Choose CopilotSidebar for persistent chat, CopilotPopup for on-demand
• ui-custom-labels - Always customize labels for your domain instead of defaults
• ui-welcome-screen - Provide a welcome screen with suggested prompts
• ui-input-mode - Use appropriate inputMode for your use case

6. Suggestions (LOW)

• suggestions-configure - Use useConfigureSuggestions (v2) or useCopilotChatSuggestions (v1)
• suggestions-context-driven - Provide rich context so suggestions are relevant
• suggestions-loading-state - Handle suggestion loading states via useSuggestions (v2)

How to Use

Read individual rule files for detailed explanations and code examples:

rules/provider-runtime-url.md
rules/agent-use-agent-updates.md
rules/tool-typed-args.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md