aiskillstore/marketplace / skills/92bilal26/chatkit-botbuilder
chatkit-botbuilder
VerifiedGuide for creating production-grade ChatKit chatbots that integrate OpenAI Agents SDK with MCP tools and custom backends. Use when building AI-powered chatbots with specialized capabilities, real-time task execution, and user isolation for any application.
| File | Kind | Size |
|---|---|---|
| CHATKIT_SKILL_SUMMARY.md | markdown | 11.3 KB |
| SKILL.md | skill md | 13.7 KB |
| references/backend_architecture.md | markdown | 10.9 KB |
| references/frontend_integration.md | markdown | 10.2 KB |
| references/mcp_wrapper_guide.md | markdown | 12.2 KB |
| references/user_isolation.md | markdown | 13.0 KB |
| skill-report.json | config | 209.3 KB |
CHATKIT_SKILL_SUMMARY.md
View on GitHub# ChatKit Botbuilder Skill - Complete Summary
## π― What Was Created
A comprehensive, production-ready skill for building ChatKit chatbots with full OpenAI Agents SDK and MCP tool integration.
**Skill Location:** `~/.claude/skills/chatkit-botbuilder/`
## π Skill Contents
### 1. SKILL.md (Main Guide - 510 lines)
Complete documentation covering:
- **Architecture Overview** - High-level data flow diagram
- **Quick Start Workflow** - Three-phase implementation guide
- Phase 1: Backend Setup (FastAPI)
- Phase 2: Frontend Setup (Next.js + React)
- Phase 3: Tool Implementation (MCP)
- **Core Patterns & Best Practices** - User isolation, streaming, threading
- **Integration Patterns** - Task management, multi-app deployment, real-time collaboration
- **Common Issues & Solutions** - Troubleshooting guide
- **Advanced Topics** - WebSockets, custom schemas, session persistence
- **Verification Checklist** - 11-point checklist for implementation
### 2. Reference Documentation (46,000+ characters)
#### `references/backend_architecture.md`
Complete FastAPI ChatKit server implementation including:
- JWT authentication middleware
- CustomChatKitStore implementation
- MyChatKitServer class with respond() method
- FastAPI endpoint configuration
- MCP tool registration
- User isolation through three levels
- Testing strategies
- Implementation checklist
#### `references/frontend_integration.md`
Next.js ChatKit widget configuration including:
- Environment setup and dependencies
- ChatKit configuration file (chatkit-config.ts)
- Authenticated fetch wrapper
- ChatKit widget component
- Dashboard integration
- Auto-refresh for real-time sync
- Authentication flow
- Debugging guide
- Performance tips
#### `references/mcp_wrapper_guide.md`
Complete guide to MCP tool wrapper functions including:
- The problem and solution
- How wrappers work (closure pattern)
- Complete wrapper implementations for all 6 tools
- Integration in ChatKit server
- Why wrappers are necessary
- Creating wrappers programmatically
- Testing strategies
- Debugging common issues
- Performance considerations
- Implementation checklist
#### `references/user_isolation.md`
Comprehensive security guide including:
- Three-level isolation strategy (middleware, tool, database)
- Complete data flow with isolation
- Verification checklist
- Common isolation failures and fixes
- Testing for isolation
- Security best practices
- Debugging isolation issues
- Compliance and auditing
## π Quick Start
When you need to build a ChatKit chatbot:
1. **Read:** `SKILL.md` - Get overview and architecture understanding
2. **Reference:** `backend_architecture.md` - Implement FastAPI backend
3. **Reference:** `frontend_integration.md` - Setup Next.js frontend
4. **Reference:** `mcp_wrapper_guide.md` - Create tool wrappers
5. **Reference:** `user_isolation.md` - Ensure security
## π‘ Key Features
β
**Complete Architecture Pattern**
- Full FastAPI backend implementation
- Next.js frontend integration
- OpenAI Agents SDK integration
- MCP tool wrapper pattern
β
**User Isolation Guarantee**
- Three-level security (middleware, tool, database)
- Verified patterns from TaskPilotAI
- Comprehensive testing strategies
β
**Real-Time Synchronization**
- Auto-refresh mechanism
- ChatKit β Dashboard sync
- Polling-based real-time updates
β
**Production Ready**
- Error handling
- Logging strategies
- Performance optimization tips
- Debugging guides
- Security best practices
## π Skill Size
| Component | Size | Purpose |
|-----------|------|---------|
| SKILL.md | 14 KB | Main guide with architecture & patterns |
| backend_architecture.md | 11 KB | FastAPI server implementation details |
| frontend_integration.md | 10 KB | Next.js widget setup & integration |
| mcp_wrapper_guide.md | 12 KB | Tool wrapper patterns & examples |
| user_isolation.md | 13 KB | Security & isolation verification |
| **Total** | **60 KB** | **Complete implementation guide** |
## π Use Cases
This skill enables Claude to help you:
1. **Build a new ChatKit chatbot from scratch**
- Architecture guidance
- Code examples for each component
- Step-by-step implementation
2. **Integrate ChatKit into existing apps**
- FastAPI backend integration
- Next.js frontend integration
- Real-time synchronization
3. **Create specialized AI assistants**
- Custom MCP tool integration
- Domain-specific chatbot design
- Multi-user system setup
4. **Fix ChatKit integration issues**
- Troubleshooting guide
- Common problems and solutions
- Debugging strategies
5. **Ensure user isolation and security**
- Three-level isolation verification
- Security best practices
- Testing strategies
6. **Deploy ChatKit to production (Vercel + Render)**
- OpenAI domain verification setup
- Environment variable configuration
- CORS and security headers
- Multi-environment management
## π Learning Value
This skill demonstrates:
- **Modern AI Architecture** - How to integrate OpenAI Agent SDK with custom backends
- **Full-Stack Development** - Frontend (Next.js), Backend (FastAPI), Database
- **Security Patterns** - JWT authentication, user isolation, data filtering
- **Tool Integration** - MCP tools, tool wrappers, automatic parameter injection
- **Real-Time Systems** - Auto-refresh, polling, synchronization
- **Production Patterns** - Error handling, logging, testing, debugging
- **OpenAI Domain Verification** - ChatKit SDK domain verification for production deployments
- **Multi-Platform Deployment** - Vercel frontend + Render backend configuration
## β¨ Examples Included
- JWT token extraction from localStorage
- ChatKit configuration with custom fetch
- MCP tool wrapper with closure pattern
- FastAPI ChatKit endpoint implementation
- Database queries with user_id filtering
- User isolation verification tests
## π Production Deployment Guide (NEW)
### OpenAI Domain Verification for ChatKit SDK
When deploying ChatKit to production, the official `@openai/chatkit-react` SDK requires domain verification:
#### Problem Solved
```
Error: Domain verification failed for https://task-pilot-ai-ashen.vercel.app
POST https://api.openai.com/v1/chatkit/domain_keys/verify 400 (Bad Request)
```
#### Solution: OpenAI Domain Registration
1. **Register Domain at OpenAI Platform**
- Go to: https://platform.openai.com/settings/organization/security/domain-allowlist
- Click "+ Add domain"
- Enter your production domain (e.g., `task-pilot-ai-ashen.vercel.app`)
- OpenAI generates a **public key** (e.g., `domain_pk_694d951d300881908730eaa457e5605809652cfa18d7a99a`)
2. **Configure Frontend (chatkit-config.ts)**
```typescript
// Use the PUBLIC KEY from OpenAI as the domainKey
const DOMAIN_PUBLIC_KEY = process.env.NEXT_PUBLIC_DOMAIN_PUBLIC_KEY || 'domain_pk_694d951d300881908730eaa457e5605809652cfa18d7a99a'
// IMPORTANT: domainKey must be the actual public key, NOT a custom identifier
const DOMAIN_KEY = DOMAIN_PUBLIC_KEY
export const chatKitConfig: UseChatKitOptions = {
api: {
url: API_URL,
domainKey: DOMAIN_KEY, // Must be OpenAI's public key
fetch: authenticatedFetch,
},
// ... rest of config
}
```
3. **Add Environment Variables to Vercel**
- `NEXT_PUBLIC_DOMAIN_PUBLIC_KEY` = `domain_pk_...` (from OpenAI)
- `NEXT_PUBLIC_API_URL` = Your backend URL
- `NEXT_PUBLIC_OPENAI_API_KEY` = Optional (if frontend needs direct OpenAI access)
4. **Render Backend Configuration**
- `OPENAI_API_KEY` = Your OpenAI API key (for agent execution)
- `CHATKIT_DOMAIN_ALLOWLIST` = List of allowed domains
- `CORS_ORIGINS` = Include Vercel URL
#### Key Insights
- β **DON'T** use custom domain identifiers (e.g., `'taskpilot-production'`)
- β
**DO** use the actual public key from OpenAI's domain registration
- β
The SDK validates this key against OpenAI's registry
- β
400 error means wrong domain key - check OpenAI platform registration
## π Related Skills
- **mcp-builder** - For building additional MCP tools
- **frontend-design** - For creating polished UI components
- **nextjs-devtools** - For Next.js-specific development
- **skill-creator** - For creating additional custom skills
## π Implementation Notes
All examples are based on the actual TaskPilotAI implementation:
- Real code from /backend/routes/chatkit.py
- Real frontend from /frontend/components/ChatKit/
- Verified patterns from TaskPilotAI Phase 2
The skill captures the complete architectural knowledge needed to build ChatKit chatbots.
## π― Success Criteria
You've successfully used this skill when:
- β
ChatKit endpoint receives user messages
- β
Agent can call MCP tools with user context
- β
Tasks created in ChatKit appear in dashboard
- β
Each user sees only their own data
- β
Real-time sync works between ChatKit and UI
- β
All security checks pass
## π Support & Troubleshooting
### Common Issues & Solutions
#### Issue 1: Domain Verification Error (Production)
**Error:** `Domain verification failed for https://yourapp.vercel.app`
- β Problem: Using custom domain key instead of OpenAI's public key
- β
Solution: Register domain at https://platform.openai.com/settings/organization/security/domain-allowlist
- β
Use the generated public key in `chatkit-config.ts`
- β
Add `NEXT_PUBLIC_DOMAIN_PUBLIC_KEY` to Vercel environment
#### Issue 2: 400 Bad Request on Domain Verification
**Error:** `POST https://api.openai.com/v1/chatkit/domain_keys/verify 400`
- β Problem: Domain key format is wrong
- β
Solution: Verify `domainKey` is in format `domain_pk_...` (not custom string)
- β
Check OpenAI platform - copy exact public key shown there
#### Issue 3: ChatKit Works Locally but Not in Production
**Error:** Works on `localhost:3000` but fails on production domain
- βΉοΈ Reason: Localhost bypasses domain verification in dev
- β
Solution: Register production domain at OpenAI platform (see Production Deployment Guide)
### General Troubleshooting Steps
If you encounter issues:
1. **Check Environment Variables**
- Vercel: Settings β Environment Variables
- Render: Settings β Environment
- Verify all `NEXT_PUBLIC_*` variables are set
2. **Review Documentation**
- SKILL.md - Common Issues & Solutions section
- Reference guides (backend, frontend, wrapper, isolation)
3. **Verify Checklist Items**
- Each component against implementation checklists
- Domain registration at OpenAI platform
- Correct public key in `chatkit-config.ts`
4. **Enable Debug Logging**
- Check browser console (F12) for errors
- Check Render logs for backend issues
- Look for specific error codes (400, 401, 403, 404)
5. **Test Each Component**
- Test backend locally first
- Test frontend locally with mock API
- Test isolation level separately
- Test domain verification with curl/postman
---
**Status:** β
Complete and Validated
**Created:** 2025-12-25
**Updated:** 2025-12-27
**Version:** 1.1
**Validation:** Passed skill-creator validation + Production Deployment (Vercel + Render)
### Recent Updates (v1.1)
- β
Added Production Deployment Guide for OpenAI domain verification
- β
Documented domain registration process and public key configuration
- β
Added troubleshooting for domain verification errors
- β
Included Vercel + Render environment variable setup
- β
Added 3 common production deployment issues and solutions
- β
Real-world validation: TaskPilotAI Phase 3 ChatKit integration
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |