Better Chatbot

better-chatbot

Status: Production Ready ✅ Last Updated: 2025-11-04 (v2.1.0 - Added extension points + UX patterns) Production Tested: https://betterchatbot.vercel.app

---

Auto-Trigger Keywords

Claude Code automatically discovers this skill when you mention:

Primary Keywords

• better-chatbot
• better chatbot
• betterchatbot
• chatbot contribution
• chatbot development

Secondary Keywords

• server action validators
• validatedActionWithUser
• validatedActionWithAdminPermission
• MCP tools
• workflow builder
• DAG workflows
• tool abstraction
• Vercel AI SDK chatbot
• Next.js chatbot
• multi-AI provider
• repository pattern
• three-tier tool system
• progressive enhancement architecture
• streaming-first design
• compound component pattern
• defensive programming
• safe() wrapper
• shared business logic
• tool lifecycle
• API route patterns

Error-Based Keywords

• "unauthorized users accessing actions"
• "tool type mismatch"
• "FormData parsing error"
• "password mismatch validation"
• "workflow state not updating"
• "E2E tests failing on clean database"
• "missing environment variables"
• "conventional commit format"
• "how to add new tool"
• "how to add API route"
• "repository implementation"
• "database query optimization"
• "component composition pattern"
• "tool rendering separation"
• "@mention system"
• "tool choice mode"
• "preset configuration"
• "extension points"

---

What This Skill Does

This skill provides project-specific coding conventions, repository structure standards, testing patterns, architectural principles, and contribution guidelines for the better-chatbot project. It ensures contributions follow established patterns and understand the "why" behind design decisions.

Core Capabilities

✅ API architecture & design patterns (route handlers, shared logic, streaming) ✅ Three-tier tool system (MCP, Workflow, Default) ✅ Component & design philosophy (compound patterns, separation of concerns) ✅ Database & repository patterns (interface-first, query optimization) ✅ Architectural principles (progressive enhancement, defensive programming) ✅ Practical templates (adding tools, routes, repositories) ✅ Server action validators (auth, validation, FormData) ✅ Workflow execution patterns (DAG streaming) ✅ Playwright E2E test orchestration ✅ Conventional Commit enforcement

---

Known Issues This Skill Prevents

Issue	Why It Happens	How Skill Fixes It
Unauthorized access to server actions	Manual auth checks are inconsistent	Use validatedActionWithUser validators
Tool type runtime errors	Not checking tool type before execution	Use branded type tags (.isMaybe())
FormData parsing errors	Manual parsing with ad-hoc validation	Validators handle parsing automatically
Cross-field validation failures	Separate validation for related fields	Use Zod superRefine pattern
Workflow state not updating	Deep mutation of nested state	Use shallow Zustand updates
E2E tests failing on clean DB	Running standard tests before first-user	Use pnpm test:e2e (includes first-user)
Missing environment variables	Not copying .env.example	Auto-generated on pnpm i
CI/CD failures from commits	Non-conventional commit format	Use prefix + colon format

---

When to Use This Skill

✅ Use When:

• Contributing to the better-chatbot repository
• Working in a better-chatbot fork/clone
• Following better-chatbot conventions for custom deployment
• Implementing server action validators
• Setting up Playwright E2E tests for better-chatbot
• Understanding tool abstraction patterns
• Building workflow execution features

❌ Don't Use When:

• Building a new AI chatbot from scratch (use better-chatbot-patterns instead)
• Working on non-better-chatbot projects
• Need generic Next.js/React guidance (use official docs)
• Adapting patterns for different architectures

---

Quick Usage Example

# Fork and clone better-chatbot
git clone https://github.com/YOUR-USERNAME/better-chatbot.git
cd better-chatbot

# Install dependencies (auto-generates .env)
pnpm i

# Configure environment (DATABASE_URL, at least one LLM_API_KEY)
# Edit .env file

# Start development
pnpm dev

# Create feature branch
git checkout -b feat/my-feature

# Make changes following better-chatbot conventions
# (Claude Code will use this skill automatically)

# Run quality checks
pnpm check

# Run E2E tests (if applicable)
pnpm test:e2e

# Commit with Conventional Commit format
git commit -m "feat: add my feature"

# Push and create PR
git push origin feat/my-feature

Result: Contributions that follow better-chatbot standards with zero preventable errors

Full instructions: See SKILL.md

---

Package Versions (Verified 2025-10-29)

Package	Version	Status
next	15.3.2	✅ Latest stable
ai	5.0.82	✅ Latest stable
better-auth	1.3.34	✅ Latest stable
drizzle-orm	0.41.0	✅ Latest stable
@modelcontextprotocol/sdk	1.20.2	✅ Latest stable
zod	3.24.2	✅ Latest stable
zustand	5.0.3	✅ Latest stable
vitest	3.2.4	✅ Latest stable
@playwright/test	1.56.1	✅ Latest stable

---

Dependencies

Prerequisites: None

Integrates With:

• better-chatbot-patterns (optional - for extracting reusable patterns)
• nextjs (optional - for general Next.js knowledge)
• ai-sdk-core (optional - for Vercel AI SDK details)

---

File Structure

better-chatbot/
├── SKILL.md              # Complete documentation with architecture deep-dive
├── README.md             # This file (quick reference)
└── references/           # Upstream docs from better-chatbot repo
    ├── AGENTS.md         # Full repository guidelines
    └── CONTRIBUTING.md   # Complete contribution process

---

Official Documentation

• better-chatbot: https://github.com/cgoinglove/better-chatbot
• Live Demo: https://betterchatbot.vercel.app
• Next.js: https://nextjs.org/docs
• Vercel AI SDK: https://sdk.vercel.ai/docs
• Better Auth: https://www.better-auth.com/docs
• Drizzle ORM: https://orm.drizzle.team/docs
• Playwright: https://playwright.dev/docs/intro

---

Related Skills

• better-chatbot-patterns - Reusable templates extracted from better-chatbot for custom deployments
• nextjs - General Next.js 15 knowledge (if available)
• ai-sdk-core - Vercel AI SDK v5 core concepts (if available)

---

Contributing

Found an issue or have a suggestion?

• Open an issue: https://github.com/secondsky/claude-skills/issues
• See SKILL.md for detailed documentation

---

License

MIT License - See main repo LICENSE file

---

Production Tested: https://betterchatbot.vercel.app (48+ E2E tests passing) Token Savings: ~60% Error Prevention: 100% (8 documented issues prevented) Ready to use! See SKILL.md for complete setup.