🚀 Kimi k2.5 Template

Production-ready Next.js 16 template optimized for AI-assisted development with 29 specialized skills.

---

✨ About

This project is a demo/template specifically designed for Kimi k2.5, showcasing:

• 🤖 Optimal integration with Kimi k2.5 via a structured skill system
• 🏗️ A modern tech stack (Next.js 16, React 19, Tailwind CSS 4)
• 📚 29 specialized skills to accelerate development
• 🎯 Patterns and best practices validated for React 19 and Next.js App Router

---

🛠️ Tech Stack

Technology	Version	Description
Next.js	16.1.6	React framework with App Router
React	19.2.4	UI library with Server Components
TypeScript	5.9.3	Strict type safety
Tailwind CSS	4.1.18	Utility-first CSS with @theme
Geist Font	latest	Vercel font family (Sans + Mono)
pnpm	-	Fast package manager

UI & Data Libraries

• shadcn/ui — Radix UI components + Tailwind
• TanStack Query — Data fetching and caching
• Motion (Framer Motion) — React animations
• Zustand — Lightweight state management
• Recharts — Data visualization
• Zod — TypeScript schema validation

---

🎓 Kimi Skills (29 Specializations)

The project includes 29 specialized skills in .agents/skills/ to guide Kimi k2.5:

🎯 Planning & Architecture

Skill	Description
plan-master	Systematic planning methodology
subagent-tasker	Best practices for parallel tasks
post-review	Systematic post-implementation code review

🏗️ Frontend Development

Skill	Description
nextjs-16-tailwind-4	Next.js 16 + Tailwind 4 + React 19 patterns
shadcn-ui	shadcn/ui components and Charts
frontend-design	Distinctive, production-grade UI design
motion-animations	Motion (Framer Motion) animations
component-generator	React component generator
next-intl-i18n	Internationalization (i18n)
forms-master	Forms with React 19 + Zod + Server Actions

🔄 Data & State Management

Skill	Description
tanstack-query	Data fetching with TanStack Query
zustand-state	State management with Zustand
drizzle-orm	Drizzle ORM + Neon PostgreSQL
neon-postgresql	Neon PostgreSQL serverless database
react-custom-hooks	Custom React hooks

🔧 Backend & API

Skill	Description
next-api-routes	API Routes & Server Actions
better-auth	Authentication with Better Auth

✅ Quality & Security

Skill	Description
testing-vitest	Testing with Vitest + React Testing Library
accessibility-a11y	Web accessibility (a11y)
security-best-practices	Security best practices
git-workflow	Git best practices (commits, branches, PRs)
source-of-truth	Official documentation reference
migration-refactor	Refactoring and migrations
deployment-vercel	Vercel deployment
docker-deployment	Docker containerization
nextjs-seo	SEO optimization (metadata, OG, sitemap)
performance-optimization	Performance & Core Web Vitals
vercel-react-best-practices	React & Next.js best practices (Vercel)

---

📁 Project Structure

kimi-template/
├── .agents/
│   └── skills/                 # 🎓 Kimi Skills (29 specializations)
│       ├── SKILL_AUDIT_MASTER.md
│       ├── plan-master/
│       ├── nextjs-16-tailwind-4/
│       ├── shadcn-ui/
│       ├── tanstack-query/
│       ├── motion-animations/
│       └── ...
│
├── src/
│   ├── app/                    # 📱 Next.js App Router
│   │   ├── layout.tsx          # Root layout with fonts & metadata
│   │   ├── page.tsx            # Home page
│   │   ├── dashboard/          # Example: Dashboard page
│   │   │   └── page.tsx
│   │   ├── globals.css         # Global styles + Tailwind theme
│   │   └── favicon.ico
│   │
│   ├── components/             # 🧩 React Components
│   │   ├── ui/                 # shadcn/ui components
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── chart.tsx
│   │   │   └── ...
│   │   ├── animations/         # Motion animation components
│   │   │   ├── fade-in.tsx
│   │   │   ├── card-hover.tsx
│   │   │   └── ...
│   │   ├── dashboard/          # Dashboard business components
│   │   │   ├── stats-grid.tsx
│   │   │   ├── revenue-chart.tsx
│   │   │   └── ...
│   │   └── providers/          # React Providers
│   │       └── query-provider.tsx
│   │
│   ├── hooks/                  # 🎣 Custom hooks
│   │   └── use-dashboard.ts
│   │
│   └── lib/                    # 📚 Utilities and config
│       ├── utils.ts            # Utility functions (cn, etc.)
│       ├── query-client.ts     # TanStack Query config
│       ├── query-keys.ts       # Query keys
│       ├── api/                # API clients
│       │   └── dashboard.ts
│       └── types/              # TypeScript types
│           └── dashboard.ts
│
├── public/                     # 📦 Static assets
├── package.json                # Dependencies
├── next.config.ts              # Next.js config
├── tsconfig.json               # TypeScript config
├── eslint.config.mjs           # ESLint config
└── AGENTS.md                   # 📖 Complete agent documentation

---

🚀 Quick Start

Option 1: Use GitHub Template (Recommended)

Click the green "Use this template" button at the top of this page, or:

# Create a new repo from this template
git clone --depth 1 https://github.com/CaseReed/kimi-template.git my-app
cd my-app
rm -rf .git
git init

Option 2: Clone Directly

git clone https://github.com/CaseReed/kimi-template.git
cd kimi-template

Prerequisites

• Node.js 20+
• pnpm (recommended)

Setup

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your values

# Start the development server
pnpm dev

Open http://localhost:3000 to see the result.

🌐 Live Demo

See it in action: kimi-template.vercel.app

Available Scripts

pnpm dev          # Development server
pnpm build        # Production build
pnpm start        # Start production server
pnpm lint         # ESLint
pnpm clean        # Full cleanup (node_modules, .next, etc.)

---

🔐 Authentication

The project includes a complete authentication system powered by Better Auth:

• 🔑 Email/Password authentication with secure session management
• 🔐 OAuth providers (GitHub, Google) - configurable
• 🛡️ Protected routes with Server Components
• 📧 Session management with HTTP-only cookies
• 🌍 i18n support for login/register pages

Quick Start Auth

# 1. Start PostgreSQL database
docker-compose -f docker-compose.db.yml up -d

# 2. Configure environment
cp .env.example .env.local
# Edit .env.local with your values

# 3. Run migrations
pnpm db:push

# 4. Create admin user
pnpm db:seed:admin

# 5. Start the app
pnpm dev

Configure OAuth Providers

See Better Auth Documentation for detailed instructions on configuring GitHub and Google OAuth.

---

🎨 Example: Included Dashboard

The project includes a complete Dashboard page (/dashboard) demonstrating:

• 📊 Charts with Recharts (revenue, categories)
• 📈 Statistics with Motion animations
• 📋 Transaction table with pagination
• 🔄 Data fetching with TanStack Query
• 🎯 Optimistic UI with React 19

Perfect for understanding how skills integrate in a real-world case!

---

📝 How to Use Skills

In Kimi k2.5, use skills with the /skill:skill-name syntax:

# Examples:
/skill:plan-master          # To plan a complex feature
/skill:component-generator  # To generate a new component
/skill:shadcn-ui           # To add UI components
/skill:tanstack-query      # To implement data fetching
/skill:forms-master        # To create a form
/skill:post-review         # To review code after implementation

💡 Golden Rule: Always end with /skill:post-review before marking a feature as complete!

---

📖 Documentation

• AGENTS.md — Complete project documentation for agents
• SKILL_AUDIT_MASTER.md — Skills audit and status
• Individual skills — See .agents/skills/<skill-name>/SKILL.md

---

🔐 Security

• Environment variables: use .env.local (never committed)
• Only NEXT_PUBLIC_* variables are exposed to the client
• ESLint includes React and Next.js security rules

---

📄 License

MIT — Free to use for your own projects.

---

Built with ❤️ for Kimi k2.5