How Kits Work

Under the hood of aiorg kits.

Kit Architecture

Every kit contains four components that work together:

.claude/
├── commands/           # Procedures Claude executes
├── knowledge/          # Domain knowledge Claude reads
├── skills/             # Reusable capabilities
└── guides/             # Guides for YOU to read

---

Commands

Commands are procedures Claude executes.

Located in .claude/commands/. Each command is a markdown file that tells Claude exactly what to do.

Example: /setup Command

# /setup

Set up the project for first use.

## Steps

1. Check prerequisites (Node.js, Docker)
2. Install dependencies with pnpm
3. Create .env.local from template
4. Start local services
5. Verify everything works

## Prerequisites Check

Run these commands to verify:
- node --version (requires 20+)
- docker --version (requires Docker Desktop)

How It Works

When you type /setup in Claude Code:

1. Claude reads .claude/commands/setup.md
2. Follows the steps exactly
3. Uses tools (Bash, Read, Write) to execute
4. Reports progress and results

Command Patterns

---

Knowledge

Knowledge is information Claude reads to understand your domain.

Located in .claude/knowledge/. Claude reads these files at session start.

Example: Kit Ecosystem Knowledge

# Kit Ecosystem

## Which Kit for Which Problem

| Problem | Kit |
|---------|-----|
| "Is this worth building?" | Idea OS |
| "How do I get users?" | Marketing OS |
| "Users sign up but leave" | PMF OS |
| "How do I keep users?" | Success OS |

How It Works

1. Claude loads knowledge files on session start
2. Uses them to answer questions accurately
3. References them when relevant

Knowledge vs Commands

---

Skills

Skills are reusable capabilities Claude can activate.

Located in .claude/skills/. Each skill gives Claude specialized expertise.

Example: Supabase Expert Skill

# Supabase Expert

## Activation

Activate when user asks about:
- Database queries
- RLS policies
- Migrations
- Supabase functions

## Knowledge

### RLS Best Practices
- Always use auth.uid() for user isolation
- Enable RLS on every table
- Test policies with different users

### Common Patterns
[Database patterns, query examples, etc.]

How It Works

1. Skills activate based on context
2. Claude gains specialized knowledge
3. Better answers for that domain

Built-in Skills

---

Guides

Guides are documentation for YOU, not Claude.

Located in .claude/guides/ or recipes/. These are meant for human reading.

Example: Recipe

# Add Google OAuth

Step-by-step guide to add Google authentication.

## Prerequisites
- Google Cloud Console account
- OAuth credentials created

## Steps

### 1. Create OAuth Credentials
Go to console.cloud.google.com...

### 2. Configure Supabase
In your Supabase dashboard...

### 3. Update Environment Variables
Add to .env.local...

How It Works

1. You run /recipes to browse guides
2. Select a guide to read
3. Follow the steps yourself (or ask Claude to help)

Guides vs Commands

---

CLAUDE.md

The main context file at the project root.

What It Contains

# Project Name

## Overview
What this project does.

## Tech Stack
- Framework: Next.js 15
- Database: Supabase
- Payments: Stripe

## Project Structure
Where things are located.

## Key Commands
Available slash commands.

## Development
How to run and build.

How It Works

1. Claude reads CLAUDE.md on every session start
2. Uses it to understand your project
3. References it when answering questions

Best Practices

• Keep it accurate and up-to-date
• Focus on what Claude needs to know
• Include project-specific conventions

---

Session Flow

When you start a Claude Code session:

1. Claude reads CLAUDE.md
   └── Understands project context

2. Claude reads .claude/knowledge/*
   └── Gains domain knowledge

3. Welcome hook runs (if configured)
   └── Greets you with context

4. You type a command or question
   │
   ├── Command (/setup)
   │   └── Claude reads .claude/commands/setup.md
   │       └── Executes the procedure
   │
   └── Question ("How do RLS policies work?")
       └── Claude uses knowledge + skills
           └── Provides informed answer

---

Kit Types

Templates (Bootstrap Mode)

Create new projects from scratch.

npx @aiorg/cli init saas-starter ~/my-project

Includes:

• Full codebase (src/, supabase/, etc.)
• Claude configuration (.claude/, CLAUDE.md)
• Ready to run

Examples: SaaS Dev Team, Landing Page

Companion Tools (Inject Mode)

Add to existing projects.

cd ~/my-existing-project
npx @aiorg/cli add marketing-os

Includes:

• Kit data folder (.marketing-os/)
• Claude configuration (merged)
• No code changes to your project

Examples: Marketing OS, PMF OS, Success OS, QA Team

---

File Categories

During upgrades, files are handled differently:

This ensures:

• You get new features
• Your data is preserved
• Your customizations are respected

---

Creating Custom Commands

Add your own commands:

1. Create the File

# .claude/commands/my-command.md

2. Write the Command

# /my-command

Description of what this command does.

## Steps

1. First, do this
2. Then, do that
3. Finally, verify

## Notes

- Important consideration
- Another note

3. Use It

> /my-command

Claude reads your file and executes it.