Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From better-chatbot
Enforces better-chatbot project standards for contributions, including three-tier tool system, repository patterns, server actions, and component designs.
npx claudepluginhub secondsky/claude-skills --plugin better-chatbotHow this skill is triggered — by the user, by Claude, or both
Slash command
/better-chatbot:better-chatbotThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Status**: Production Ready
assets/example-template.txtreferences/AGENTS.mdreferences/CONTRIBUTING.mdreferences/api-architecture.mdreferences/architectural-principles.mdreferences/common-errors.mdreferences/component-patterns.mdreferences/database-patterns.mdreferences/extension-points.mdreferences/server-actions.mdreferences/templates.mdreferences/tool-system.mdreferences/ux-patterns.mdscripts/example-script.shProvides portable patterns for Next.js AI chatbots: server action validators for auth/FormData, tool abstraction with type checking, multi-AI providers, and workflow execution.
Provides Vercel AI SDK v5 React hooks (useChat, useCompletion, useObject) for streaming AI chat UIs in Next.js apps. Fixes parse stream errors, no responses, and streaming issues.
Delivers provider-agnostic type-safe LLM chat SDK with streaming, tools, agent loops for OpenAI, Anthropic, Gemini, Ollama in React, Solid, Next.js apps.
Share bugs, ideas, or general feedback.
Status: Production Ready Version: 3.0.0 (Optimized with progressive disclosure) Last Updated: 2025-12-17 Dependencies: None (references better-chatbot project) Latest Versions: Next.js 16.0.3, Vercel AI SDK 5.0.98, Better Auth 1.3.34, Drizzle ORM 0.41.0
better-chatbot is an open-source AI chatbot platform for individuals and teams, built with Next.js 15 and Vercel AI SDK v5. It combines multi-model AI support (OpenAI, Anthropic, Google, xAI, Ollama, OpenRouter) with advanced features like MCP (Model Context Protocol) tool integration, visual workflow builder, realtime voice assistant, and team collaboration.
This skill teaches Claude the project-specific conventions and patterns used in better-chatbot to ensure contributions follow established standards and avoid common pitfalls.
# Clone and install
git clone https://github.com/cgoinglove/better-chatbot.git
cd better-chatbot
pnpm install
# Configure environment
cp .env.example .env
# Add your API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
# Add database URL: DATABASE_URL="postgresql://..."
# Add auth secret: BETTER_AUTH_SECRET="your-secret"
# Run development server
pnpm dev
pnpm dev - Start development serverpnpm build - Production buildpnpm test - Run unit testspnpm test:e2e - Run E2E tests (requires DB + API keys)pnpm check - Lint + type check + tests (run before PR)better-chatbot/
├── src/
│ ├── app/ # Next.js routes + API
│ ├── components/ # UI components by domain
│ ├── lib/ # Core logic (ai, db, validations)
│ ├── hooks/ # React hooks
│ └── types/ # TypeScript types
├── tests/ # E2E Playwright tests
└── drizzle/ # Database migrations
Better-chatbot uses a three-tier tool architecture for AI capabilities:
For details: Load references/tool-system.md when implementing tools or understanding tool execution.
Routes follow RESTful conventions with streaming-first architecture and defensive programming using safe() wrapper.
For details: Load references/api-architecture.md when building API routes or implementing streaming.
Components organized by feature using compound component pattern. Tools execution separated from rendering.
For details: Load references/component-patterns.md when building UI components.
All database access abstracted through repository classes using Drizzle ORM.
For details: Load references/database-patterns.md when implementing database queries.
Error: Unauthorized users accessing protected actions
Why: Manual auth implementation is inconsistent
Prevention: Use validatedActionWithUser or validatedActionWithAdminPermission
// ❌ BAD: Manual auth check
export async function updateProfile(data: ProfileData) {
const session = await getSession()
if (!session) throw new Error("Unauthorized")
// ... rest of logic
}
// ✅ GOOD: Use validator
export const updateProfile = validatedActionWithUser(
profileSchema,
async (data, formData, user) => {
// user is guaranteed to exist, auto-error handling
}
)
Error: Runtime type errors when executing tools Why: Not checking tool type before execution Prevention: Use branded type tags for runtime narrowing
// ❌ BAD: Assuming tool type
const result = await executeMcpTool(tool)
// ✅ GOOD: Check tool type
if (VercelAIMcpToolTag.isMaybe(tool)) {
const result = await executeMcpTool(tool)
} else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
const result = await executeWorkflowTool(tool)
}
Error: Inconsistent error handling for form submissions Why: Manual FormData parsing with ad-hoc validation Prevention: Validators handle parsing automatically
// ❌ BAD: Manual parsing
const name = formData.get("name") as string
if (!name) throw new Error("Name required")
// ✅ GOOD: Validator with Zod
const schema = z.object({ name: z.string().min(1) })
export const action = validatedAction(schema, async (data) => {
// data.name is validated and typed
})
Error: Password mismatch validation not working
Why: Separate validation for related fields
Prevention: Use Zod superRefine
// ❌ BAD: Separate checks
if (data.password !== data.confirmPassword) { /* error */ }
// ✅ GOOD: Zod superRefine
const schema = z.object({
password: z.string(),
confirmPassword: z.string()
}).superRefine((data, ctx) => {
if (data.password !== data.confirmPassword) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Passwords don't match",
path: ["confirmPassword"]
})
}
})
Error: State updates not triggering re-renders Why: Mutating state directly instead of creating new objects Prevention: Use shallow updates with spread operator
// ❌ BAD: Direct mutation
set((state) => {
state.user.name = "New Name" // Mutation!
})
// ✅ GOOD: Shallow update
set((state) => ({
user: { ...state.user, name: "New Name" }
}))
For all errors: Load references/common-errors.md when debugging issues beyond the top 5.
✅ Use validatedActionWithUser or validatedActionWithAdminPermission for server actions
✅ Check tool types with branded type tags before execution
✅ Use Zod superRefine for cross-field validation
✅ Add unit tests (happy path + one failure mode)
✅ Run pnpm check before PR submission
✅ Include visual documentation for UI changes
✅ Use Conventional Commit format for PR titles
✅ Run E2E tests when touching critical flows
❌ Implement server actions without auth validators
❌ Assume tool type without runtime check
❌ Parse FormData manually (use validators)
❌ Mutate Zustand state directly (use shallow updates)
❌ Skip first-user tests on clean database
❌ Commit without running pnpm check
❌ Submit PR without visual docs (if UI change)
❌ Use non-conventional commit format
Load reference files when working on specific aspects of better-chatbot:
references/api-architecture.md)Load when:
references/tool-system.md)Load when:
references/component-patterns.md)Load when:
references/database-patterns.md)Load when:
references/architectural-principles.md)Load when:
references/extension-points.md)Load when:
references/ux-patterns.md)Load when:
references/templates.md)Load when:
references/server-actions.md)Load when:
references/common-errors.md)Load when:
references/AGENTS.md)Load when:
references/CONTRIBUTING.md)Load when:
This skill includes 12 reference files:
Technical References (10 files):
api-architecture.md - API patterns and route handlerstool-system.md - Three-tier tool architecturecomponent-patterns.md - UI component designdatabase-patterns.md - Repository pattern and Drizzle ORMarchitectural-principles.md - Design philosophyextension-points.md - How to extend the systemux-patterns.md - UX patterns and @mentionstemplates.md - Code templates for routes/tools/componentsserver-actions.md - Server action validatorscommon-errors.md - Complete error catalogRepository References (2 files):
AGENTS.md - Repository structure and development commandsCONTRIBUTING.md - Contribution workflow and PR guidelinesLoad references on-demand when specific knowledge is needed. See "When to Load References" section for triggers.
Core:
Testing:
Tools:
This skill is based on the production better-chatbot repository with 48 E2E tests covering core functionality, active development, and growing community contributions.
Last verified: 2025-12-17 | Version: 3.0.0