Agent skill
chatkit-rails-backend
Integrate OpenAI ChatKit with a Rails backend using SSE streaming. Use when building conversational AI with thread management, message streaming, widget rendering from MCP tool results, file attachments, and human-in-the-loop form interactions. Triggers on ChatKit, chat widget, thread streaming, or widget from tool result.
Install this agent skill to your Project
npx add-skill https://github.com/rbarazi/agent-skills/tree/main/skills/chatkit-rails-backend
SKILL.md
ChatKit Rails Backend Integration
Integrate OpenAI's ChatKit JavaScript widget with your Rails backend using Server-Sent Events (SSE).
Quick Start
ChatKit communicates via JSON requests to your Rails controller. The core flow:
User → ChatKit.js → Rails Controller (SSE) → Task/LLM → Tools → Stream Response
Required components:
ChatkitController- Handles protocol requests via SSEChatkitConfig- Environment-driven configuration modelChatkitAttachment- Tracks uploaded files per account/agent
Core Controller Pattern
class ChatkitController < ApplicationController
include ActionController::Live # Required for SSE
def entry
req = JSON.parse(request.raw_post.presence || "{}")
case req["type"]
when "threads.create" then stream_new_thread(req)
when "threads.add_user_message" then stream_user_message(req)
when "threads.get_by_id" then render json: thread_response(task)
when "threads.list" then render json: threads_list_response
# ... handle other events
end
end
end
SSE Streaming
def prepare_stream_headers
response.headers["Content-Type"] = "text/event-stream"
response.headers["Cache-Control"] = "no-cache"
end
def write_event(payload)
response.stream.write("data: #{payload.to_json}\n\n")
end
# Always close stream in ensure block
Widget Extraction from Tool Results
Extract widgets from MCP tool results containing ui:// resources:
def embedded_widget_item(task, message)
return unless message.role == Message::ROLE_TOOL_RESULT
widget_resource = extract_widget_resource(message)
widget_payload = parse_widget_payload(widget_resource)
{ type: "widget", widget: widget_payload[:widget], copy_text: widget_payload[:copy_text] }
end
Key detection: URI starts with ui:// + MIME type application/vnd.ui.widget+json
Reference Files
For detailed patterns, see:
- controller.md - Complete controller implementation
- streaming.md - SSE streaming and progress updates
- widgets.md - Widget extraction from tool results
- attachments.md - File upload handling
- human-interaction.md - Form-based human-in-the-loop
- testing.md - RSpec testing patterns
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
rbarazi/agent-skills
test-auth-helpers
Implement authentication testing patterns with RSpec, FactoryBot, and test helpers for Rails applications. Use when writing controller specs, system tests, or request specs that require authenticated users and multi-tenant account context.
rbarazi/agent-skills
multi-tenant-accounts
Implement multi-tenant architecture using an Account model as the tenant boundary. Use when building SaaS applications, team-based apps, or any system where data must be isolated between organizations/accounts.
rbarazi/agent-skills
user-management
Implement user CRUD operations within an account with permission controls and feature flags. Use when building team member management, user administration, or account user settings in multi-tenant Rails applications.
rbarazi/agent-skills
oauth21-provider
Implement an RFC-compliant OAuth 2.1 authorization server in Rails applications. Use when building apps that need to authorize third-party clients (like MCP clients, API consumers, or external integrations) using industry-standard OAuth flows with PKCE, dynamic client registration, and token management.
rbarazi/agent-skills
password-reset-flow
Implement secure password reset with Rails 8's built-in token generation. Use when building "forgot password" functionality with email verification and time-limited reset tokens.
rbarazi/agent-skills
code-pattern-extraction
Extract reusable design and implementation patterns from codebases into Skills. Use when asked to analyze code for patterns, document architectural decisions, create transferrable implementation guides, or extract knowledge into Skills. Transforms working implementations into comprehensive, reusable Skills that can be applied to new projects.
Didn't find tool you were looking for?