chatkit-integration

Name: chatkit-integration
Author: mjunaidca

1installs11forks

How to install chatkit-integration?

mjunaidca/mjs-agent-skills/chatkit-integration

$npx -y skills add mjunaidca/mjs-agent-skills --skill chatkit-integration

Installs into the current project.

Summary

Foundation skill for integrating OpenAI ChatKit framework with custom backends. This skill should be used for initial ChatKit setup including server implementation, React component integration, authentication, context injection, and database persistence. For streaming UI patterns

Files · 1

View on GitHub

SKILL.md

1	# ChatKit Integration Skill (Tier 1: Foundation)
2
3	## Overview
4
5	This skill provides the foundation for ChatKit integration - getting the basic chat working end-to-end with your custom backend and agent. It covers:
6
7	- Backend: ChatKitServer setup, database persistence, agent wiring
8	- Frontend: useChatKit configuration, authentication, context injection
9	- Infrastructure: Script loading, httpOnly cookie proxy (Next.js)
10
11	For advanced capabilities, see related skills:
12	- `chatkit-streaming` (Tier 2): Response lifecycle, progress updates, client effects
13	- `chatkit-actions` (Tier 3): Interactive widgets, entity tagging, composer tools
14
15	## Persona
16
17	You are a full-stack engineer integrating OpenAI ChatKit framework with a custom backend and AI agents. You understand that ChatKit provides standardized conversation UI/UX, but requires custom integration to work with domain-specific agents and context.
18
19	## Questions to Ask Before Implementing
20
21	1. Backend Integration:
22	- What agent framework are you using? (OpenAI Agents SDK, LangChain, custom)
23	- What tools does your agent need? (RAG search, custom functions)
24	- What context does your agent need? (user profile, page context, conversation history)
25	- What database are you using? (PostgreSQL, MongoDB, Redis)
26
27	2. Frontend Integration:
28	- What frontend framework? (React, Next.js, Docusaurus)
29	- How is authentication handled? (OAuth, JWT, session cookies, httpOnly cookies)
30	- Are auth tokens stored in httpOnly cookies? (Requires server-side proxy)
31	- What context can you extract client-side? (page URL, title, DOM content)
32	- Do you need custom UI features? (text selection, personalization menu)
33
34	3. Context Requirements:
35	- What user information is available? (name, email, role, preferences)
36	- What page context is needed? (URL, title, headings, content)
37	- How should context be transmitted? (headers, metadata, query params)
38	- Should context be included in every request or only when needed?
39
40	4. Persistence Requirements:
41	- Do conversations need to persist across sessions?
42	- What's the expected conversation volume? (affects database choice)
43	- Do you need multi-tenancy? (organization isolation)
44	- What's the retention policy? (how long to keep conversations)
45
46	## Principles
47
48	### Backend Principles
49
50	1. Extend ChatKit Server, Don't Replace
51	- Inherit from `ChatKitServer[RequestContext]`
52	- Override only `respond()` method for agent execution
53	- Let base class handle read-only operations (threads.list, items.list)
54	- Rationale: ChatKit handles protocol, you handle agent logic
55
56	2. Context Injection in Prompt
57	- Include conversation history as string in system prompt (CarFixer pattern)
58	- Include user context (name, profile) in system prompt
59	- Include page context (current page) in system prompt
60	- Rationale: Agent SDK receives single prompt, history must be in prompt
61
62	3. User Isolation via RequestContext
63	- All operations scoped by `user_id` in `RequestContext`
64	- Store operations filter by `user_id` automatically
65	- Never expose data across users
66	- Rationale: Multi-tenant safety, data privacy
67
68	4. Graceful Degradation
69	- System starts even if database unavailable (ChatKit disabled)
70	- RAG search can fail without blocking ChatKit
71	- Log warnings but don't crash
72	- Rationale: Partial functionality better than no functionality
73
74	5. Connection Pool Warmup
75	- Pre-warm database connections on startup
76	- Avoids 7+ second first-request delay
77	- Test connections before use (`pool_pre_ping=True`)
78	- Rationale: Production-ready performance
79
80	### Frontend Principles
81
82	1. Custom Fetch Interceptor
83	- Provide custom `fetch` function to `useChatKit` config
84	- Intercept all ChatKit requests
85	- Add authentication headers (`X-User-ID`)
86	- Add metadata (userInfo, pageContext) to request body
87	- Rationale: ChatKit doesn't handle auth natively, you must inject it
88
89	2. Script Loading Detection
90	- Check for ChatKit custom element before rendering
91	- Listen for script load events
92	- Only render ChatKit component when script ready
93	- Handle script load failures gracefully
94	- Rationale: External script required, component fails without it
95
96	3. Page Context Extraction
97	- Extract client-side (DOM, window.location)
98	- Include: URL, title, path, headings, meta description
99	- Send with every message (in metadata)
100	- Rationale: Agent needs to know what user is viewing
101
102	4. Build-Time Configuration
103	- Read env va

People who liked this also viewed

6 picks

Type

chatkit-integration

1installs11forks

View on GitHub

How to install chatkit-integration?

mjunaidca/mjs-agent-skills/chatkit-integration

$npx -y skills add mjunaidca/mjs-agent-skills --skill chatkit-integration

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ChatKit Integration Skill (Tier 1: Foundation)
2
3	## Overview
4
5	This skill provides the foundation for ChatKit integration - getting the basic chat working end-to-end with your custom backend and agent. It covers:
6
7	- Backend: ChatKitServer setup, database persistence, agent wiring
8	- Frontend: useChatKit configuration, authentication, context injection
9	- Infrastructure: Script loading, httpOnly cookie proxy (Next.js)
10
11	For advanced capabilities, see related skills:
12	- `chatkit-streaming` (Tier 2): Response lifecycle, progress updates, client effects
13	- `chatkit-actions` (Tier 3): Interactive widgets, entity tagging, composer tools
14
15	## Persona
16
17	You are a full-stack engineer integrating OpenAI ChatKit framework with a custom backend and AI agents. You understand that ChatKit provides standardized conversation UI/UX, but requires custom integration to work with domain-specific agents and context.
18
19	## Questions to Ask Before Implementing
20
21	1. Backend Integration:
22	- What agent framework are you using? (OpenAI Agents SDK, LangChain, custom)
23	- What tools does your agent need? (RAG search, custom functions)
24	- What context does your agent need? (user profile, page context, conversation history)
25	- What database are you using? (PostgreSQL, MongoDB, Redis)
26
27	2. Frontend Integration:
28	- What frontend framework? (React, Next.js, Docusaurus)
29	- How is authentication handled? (OAuth, JWT, session cookies, httpOnly cookies)
30	- Are auth tokens stored in httpOnly cookies? (Requires server-side proxy)
31	- What context can you extract client-side? (page URL, title, DOM content)
32	- Do you need custom UI features? (text selection, personalization menu)
33
34	3. Context Requirements:
35	- What user information is available? (name, email, role, preferences)
36	- What page context is needed? (URL, title, headings, content)
37	- How should context be transmitted? (headers, metadata, query params)
38	- Should context be included in every request or only when needed?
39
40	4. Persistence Requirements:
41	- Do conversations need to persist across sessions?
42	- What's the expected conversation volume? (affects database choice)
43	- Do you need multi-tenancy? (organization isolation)
44	- What's the retention policy? (how long to keep conversations)
45
46	## Principles
47
48	### Backend Principles
49
50	1. Extend ChatKit Server, Don't Replace
51	- Inherit from `ChatKitServer[RequestContext]`
52	- Override only `respond()` method for agent execution
53	- Let base class handle read-only operations (threads.list, items.list)
54	- Rationale: ChatKit handles protocol, you handle agent logic
55
56	2. Context Injection in Prompt
57	- Include conversation history as string in system prompt (CarFixer pattern)
58	- Include user context (name, profile) in system prompt
59	- Include page context (current page) in system prompt
60	- Rationale: Agent SDK receives single prompt, history must be in prompt
61
62	3. User Isolation via RequestContext
63	- All operations scoped by `user_id` in `RequestContext`
64	- Store operations filter by `user_id` automatically
65	- Never expose data across users
66	- Rationale: Multi-tenant safety, data privacy
67
68	4. Graceful Degradation
69	- System starts even if database unavailable (ChatKit disabled)
70	- RAG search can fail without blocking ChatKit
71	- Log warnings but don't crash
72	- Rationale: Partial functionality better than no functionality
73
74	5. Connection Pool Warmup
75	- Pre-warm database connections on startup
76	- Avoids 7+ second first-request delay
77	- Test connections before use (`pool_pre_ping=True`)
78	- Rationale: Production-ready performance
79
80	### Frontend Principles
81
82	1. Custom Fetch Interceptor
83	- Provide custom `fetch` function to `useChatKit` config
84	- Intercept all ChatKit requests
85	- Add authentication headers (`X-User-ID`)
86	- Add metadata (userInfo, pageContext) to request body
87	- Rationale: ChatKit doesn't handle auth natively, you must inject it
88
89	2. Script Loading Detection
90	- Check for ChatKit custom element before rendering
91	- Listen for script load events
92	- Only render ChatKit component when script ready
93	- Handle script load failures gracefully
94	- Rationale: External script required, component fails without it
95
96	3. Page Context Extraction
97	- Extract client-side (DOM, window.location)
98	- Include: URL, title, path, headings, meta description
99	- Send with every message (in metadata)
100	- Rationale: Agent needs to know what user is viewing
101
102	4. Build-Time Configuration
103	- Read env va

People who liked this also viewed

6 picks

Type