Skip to content

aiskillstore/marketplace / skills/92bilal26/chatkit-botbuilder

chatkit-botbuilder

Verified

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

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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall