This skill provides project-specific coding conventions, architectural principles, repository structure standards, testing patterns, and contribution guidelines for the better-chatbot project (https://github.com/cgoinglove/better-chatbot). Use this skill when contributing to or working with better-chatbot to understand the design philosophy and ensure code follows established patterns. Includes: API architecture deep-dive, three-tier tool system (MCP/Workflow/Default), component design patterns, database repository patterns, architectural principles (progressive enhancement, defensive programming, streaming-first), practical templates for adding features (tools, routes, repositories). Use when: working in better-chatbot repository, contributing features/fixes, understanding architectural decisions, following server action validators, implementing tools/workflows, setting up Playwright tests, adding API routes, designing database queries, building UI components, handling multi-AI provider integration Keywords: better-chatbot, chatbot contribution, better-chatbot standards, chatbot development, AI chatbot patterns, API architecture, three-tier tool system, repository pattern, progressive enhancement, defensive programming, streaming-first, compound component pattern, Next.js chatbot, Vercel AI SDK chatbot, MCP tools, workflow builder, server action validators, tool abstraction, DAG workflows, shared business logic, safe() wrapper, tool lifecycle
Status: Production Ready ✅ Last Updated: 2025-11-04 (v2.1.0 - Added extension points + UX patterns) Production Tested: https://betterchatbot.vercel.app
Claude Code automatically discovers this skill when you mention:
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.
✅ 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
| 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 |
better-chatbot-patterns instead)# 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
| Approach | Tokens Used | Errors Encountered | Time to Complete | |----------|------------|-------------------|------------------| | Manual Setup | ~12,000 | 2-3 | ~30 min | | With This Skill | ~4,800 | 0 ✅ | ~12 min | | Savings | ~60% | 100% | ~60% |
| 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 |
Prerequisites: None
Integrates With:
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
Found an issue or have a suggestion?
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.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer