You've heard about AI-assisted development. Maybe you've tried Gemini CLI or ChatGPT for coding. The results were promising but inconsistent—sometimes brilliant, sometimes frustratingly wrong.

GemKit changes the equation. Instead of generic AI that requires careful prompting, you get specialized agents that understand context, follow patterns, and produce consistent, high-quality code.

This tutorial takes you from zero to productive in 15 minutes. By the end, you'll have:

GemKit installed and configured
Your first project initialized
A working agent session that actually helps

Let's go.

What is GemKit?

GemKit is a toolkit that extends Gemini CLI with:

Feature	What It Does	Why It Matters
Specialized Agents	Pre-configured AI personas for specific tasks	No more generic prompts; agents know their role
Skills	Domain knowledge packages	React 19, TypeScript, testing patterns built-in
Workflows	Multi-step orchestration	Research → Plan → Implement → Test, automated
Agent Office	Visual dashboard	See what AI is doing in real-time

Think of it as turning Gemini CLI from a raw LLM into a team of AI specialists, each optimized for their role.

Prerequisites

Before installing GemKit, ensure you have:

Required:

Node.js 18+: Check with node --version
npm or pnpm: Comes with Node.js
Gemini API Key: Get one at Google AI Studio

Recommended:

Git: For version controlling your agent configurations
VS Code: For editing agent definitions and skills

Getting Your API Key

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the key (starts with AIza...)
Store it securely

Step 1: Install GemKit CLI

Open your terminal and run:

bash

# Install globally
npm install -g gemkit-cli

# Verify installation
gk --version
# Output: gemkit-cli v0.2.3

Using pnpm?

bash

pnpm add -g gemkit-cli

Prefer local installation?

bash

# Install in your project
npm install --save-dev gemkit-cli

# Run with npx
npx gk --version

Step 2: Configure Your API Key

GemKit needs your Gemini API key to communicate with the AI:

bash

# Set environment variable (temporary)
export GEMINI_API_KEY=AIza...your-key-here

# Make it permanent (add to your shell profile)
echo 'export GEMINI_API_KEY=AIza...your-key-here' >> ~/.bashrc
source ~/.bashrc

# Or for Zsh
echo 'export GEMINI_API_KEY=AIza...your-key-here' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

powershell

# Set for current session
$env:GEMINI_API_KEY = "AIza...your-key-here"

# Set permanently
[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "AIza...your-key-here", "User")

Step 3: Initialize Your Project

Navigate to your project directory and initialize GemKit:

bash

cd your-project

# Initialize with the Starter Kit
gk init

# Output:
# ✓ Created .gemini/agents/
# ✓ Created .gemini/extensions/
# ✓ Created .gk.json
# ✓ Copied starter agents: researcher, code-executor, tester
# ✓ Copied starter skills: research, frontend-development, backend-development, testing
#
# GemKit initialized successfully!
# Run 'gk doctor' to verify your setup.

This creates the GemKit directory structure:

markdown

your-project/
├── .gemini/
│   ├── agents/
│   │   ├── code-executor/
│   │   │   └── agent.md
│   │   ├── researcher/
│   │   │   └── agent.md
│   │   └── tester/
│   │       └── agent.md
│   └── extensions/
│       ├── frontend-development/
│       │   └── SKILL.md
│       ├── backend-development/
│       │   └── SKILL.md
│       ├── testing/
│       │   └── SKILL.md
│       └── research/
│           └── SKILL.md
├── .gk.json
└── ... your existing project files

Step 4: Verify Your Setup

Run the diagnostic command to ensure everything is configured correctly:

bash

gk doctor

Expected output:

bash

GemKit Health Check
══════════════════════════════════════════════════════

Environment
  ✓ Node.js v20.10.0 (requires >= 18.0.0)
  ✓ npm v10.2.3
  ✓ Git v2.42.0

Dependencies
  ✓ @google/gemini-cli installed
  ✓ @anthropic-ai/claude-cli installed (optional)

Configuration
  ✓ GEMINI_API_KEY configured
  ✓ .gk.json found and valid

Project Setup
  ✓ .gemini/agents/ directory exists
  ✓ .gemini/extensions/ directory exists
  ✓ 3 agents available
  ✓ 4 skills available

══════════════════════════════════════════════════════
Status: Ready to use GemKit!

Got errors? Common fixes:

"GEMINI_API_KEY not found": Set the environment variable (Step 2)
"gemini-cli not installed": Run npm install -g @google/gemini-cli
".gemini directory not found": Run gk init

Step 5: Your First Agent Session

Now for the fun part. Let's spawn your first AI agent.

Meet Your Agents

GemKit comes with three specialized agents:

Agent	Best For	Example Use Case
Researcher	Investigation, analysis, documentation	"Compare TanStack Query vs SWR"
Code-Executor	Implementation, refactoring, bug fixes	"Add OAuth authentication"
Tester	Test generation, coverage analysis	"Write tests for the auth service"

Spawning the Researcher

Let's start with the Researcher—perfect for your first session because it doesn't modify any files.

bash

gk agent spawn --agent researcher \
  --prompt "Compare React state management options in 2026: Zustand vs Jotai vs Redux Toolkit. Focus on bundle size, learning curve, and TypeScript support."

What happens:

GemKit loads the Researcher agent persona
The research skill is automatically activated
The agent searches documentation and synthesizes findings
You receive a structured comparison report

Example output:

markdown

# React State Management Comparison (2026)

## Executive Summary
For most projects, Zustand offers the best balance of simplicity and power.
Jotai excels for atomic state, while Redux Toolkit remains the choice for
complex enterprise applications.

## Detailed Comparison

### Bundle Size
| Library | Minified | Gzipped |
|---------|----------|---------|
| Zustand | 3.2 KB | 1.4 KB |
| Jotai | 5.1 KB | 2.1 KB |
| Redux Toolkit | 32 KB | 11 KB |

### Learning Curve
- **Zustand**: Minimal (2-4 hours to productive)
- **Jotai**: Low (4-8 hours, requires understanding atoms)
- **Redux Toolkit**: Moderate (1-2 days, significant concepts)

### TypeScript Support
All three have excellent TypeScript support in 2026...

## Recommendation
For your Next.js project, I recommend **Zustand** because...

Spawning the Code-Executor

Ready to write some code? The Code-Executor is your implementation partner.

bash

gk agent spawn --agent code-executor \
  --skills "frontend-development" \
  --prompt "Create a reusable Button component with variants (primary, secondary, danger), sizes (sm, md, lg), and loading state. Use TypeScript and follow React 19 patterns."

What happens:

GemKit loads the Code-Executor agent
The frontend-development skill provides React 19 patterns
The agent plans the implementation
Code is generated with proper TypeScript types
You can review and accept the changes

Example output:

typescript

// src/components/Button.tsx
import { forwardRef, type ButtonHTMLAttributes } from 'react';
import { cn } from '@/lib/utils';

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant = 'primary', size = 'md', isLoading, children, disabled, ...props }, ref) => {
    const variants = {
      primary: 'bg-blue-600 text-white hover:bg-blue-700',
      secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
      danger: 'bg-red-600 text-white hover:bg-red-700',
    };

    const sizes = {
      sm: 'px-3 py-1.5 text-sm',
      md: 'px-4 py-2 text-base',
      lg: 'px-6 py-3 text-lg',
    };

    return (
      <button
        ref={ref}
        className={cn(
          'rounded-md font-medium transition-colors focus:outline-none focus:ring-2',
          variants[variant],
          sizes[size],
          isLoading && 'opacity-50 cursor-not-allowed',
          className
        )}
        disabled={disabled || isLoading}
        {...props}
      >
        {isLoading ? (
          <span className="flex items-center gap-2">
            <LoadingSpinner className="w-4 h-4" />
            Loading...
          </span>
        ) : (
          children
        )}
      </button>
    );
  }
);

Button.displayName = 'Button';

Spawning the Tester

Got code that needs tests? The Tester agent generates comprehensive test suites.

bash

gk agent spawn --agent tester \
  --skills "testing" \
  --context src/components/Button.tsx \
  --prompt "Write comprehensive Vitest tests for this Button component. Include tests for all variants, sizes, loading state, and accessibility."

What happens:

GemKit loads the Tester agent
The agent reads your Button component
Tests are generated covering all scenarios
Accessibility tests are included

Step 6: Launch the Agent Office

Want to see what's happening in real-time? Start the visual dashboard:

bash

gk office start

# Output:
# ✓ Agent Office starting...
# ✓ Server running at http://localhost:3847
# ✓ Opening browser...

The Agent Office shows:

Active Sessions: See which agents are running
Token Usage: Track costs in real-time
Activity Feed: Watch agents execute commands
Session History: Review past interactions

Common First-Day Tasks

Here are practical examples to try right away:

Research a Technical Topic

bash

gk agent spawn --agent researcher \
  --prompt "Research best practices for implementing dark mode in Next.js 15. Include CSS variable approach, system preference detection, and persistence strategies."

Add a Feature

bash

gk agent spawn --agent code-executor \
  --skills "frontend-development" \
  --context src/components/Navigation.tsx \
  --prompt "Add a mobile hamburger menu to this navigation component. Include smooth animation and keyboard accessibility."

Generate Tests

bash

gk agent spawn --agent tester \
  --skills "testing" \
  --context src/services/auth.ts \
  --prompt "Generate Vitest tests for this authentication service. Focus on login flow, token refresh, and error handling."

Use the /code Workflow

For complete features, use the orchestrated workflow:

bash

gk agent spawn --agent code-executor \
  --workflow code \
  --prompt "Implement a contact form with email validation, spam protection, and success/error states."

This automatically:

Researches form best practices
Plans the implementation
Generates the code
Creates tests

Project Structure Reference

After initialization, here's what each directory contains:

markdown

.gemini/
├── agents/                    # Agent definitions
│   ├── code-executor/
│   │   └── agent.md          # Plan-driven implementation agent
│   ├── researcher/
│   │   └── agent.md          # Technical investigation agent
│   └── tester/
│       └── agent.md          # Test generation agent
│
├── extensions/                # Skills (knowledge packages)
│   ├── frontend-development/
│   │   └── SKILL.md          # React 19, TanStack, MUI patterns
│   ├── backend-development/
│   │   └── SKILL.md          # Node.js, APIs, databases
│   ├── testing/
│   │   └── SKILL.md          # Vitest, Jest, Playwright
│   └── research/
│       └── SKILL.md          # Research methodology
│
└── workflows/                 # Orchestration patterns
    └── code.md               # Research → Plan → Implement → Test

.gk.json                      # GemKit configuration

Troubleshooting

"Agent not found"

bash

# List available agents
gk agent list

# Output:
# Available agents:
# - code-executor: Plan-driven, test-driven code implementation
# - researcher: Multi-step technical research with source validation
# - tester: Comprehensive test generation and coverage analysis

"Skill not found"

bash

# List available skills
gk agent search "frontend"

# Output:
# Matching skills:
# - frontend-development (score: 0.95)
# - frontend-design (score: 0.78)

"API rate limited"

If you're hitting rate limits, check your usage:

bash

gk tokens summary --period today

Consider using gemini-2.0-flash for faster, cheaper operations:

bash

gk agent spawn --agent researcher --model gemini-2.0-flash \
  --prompt "Quick summary of React 19 features"

"Context too large"

Reduce context by specifying only relevant files:

bash

# Instead of entire directory
# --context src/

# Specify relevant files
--context src/services/auth.ts,src/types/user.ts

What's Next?

You've got GemKit running. Here's where to go from here:

Immediate Next Steps

Try all three agents with your actual project
Explore skills by running gk agent search "your-topic"
Watch the Agent Office to understand how agents work

Deeper Learning

Code-Executor Deep Dive - Master the implementation agent
Tester Agent Guide - Comprehensive testing strategies

Advanced Topics

Claude Integration - Use multiple AI providers
Hooks Automation - Automate your AI workflow

Questions? Join the GemKit community or check the troubleshooting guide.

Welcome to AI-native development. Let's build something great.