🚀 Kilo-Kit: Professional AI Agent Development Framework

Version: 1.0.0
Author: Kilo-Kit Team
License: Apache 2.0

🎯 What is Kilo-Kit?

Kilo-Kit is a comprehensive, modular framework for building and managing AI agent systems at scale (kilo-code = thousands of lines, hundreds of files). It introduces a revolutionary Cognitive Flow Architecture (CFA) that treats AI interactions as continuous flows rather than discrete events.

Core Philosophy

🧠 "Anticipate needs before they arise"
🔄 "Learn from every interaction"
📐 "Modularity enables scalability"
🎯 "Quality over quantity in every token"
💰 "Cost-aware intelligence"

✨ Key Innovations

✨ Key Features

💡 Skill Library

skills/ is the canonical workflow surface for Kilo-Kit. It supports the same Progressive Disclosure model as the core framework: scan the index first, load one skill body when routed, then open references/scripts only when needed.

Install the Full Skill Library

This installs every valid SKILL.md under skills/, including Kilo-Kit core skills and the expanded category library.

npx skills@latest add VoDaiLocz/KILO-KIT

Use this when you want the entire Kilo-Kit workflow surface available in your agents.

Install a Category

Use a category path when you only want one execution domain:

npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering

Install a Single Skill

npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering/tdd

📁 Project Structure

kilo-kit/
├── README.md                    # This file
├── QUICKSTART.md               # 15-minute getting started guide
├── CONTRIBUTING.md             # Contribution guidelines
├── CHANGELOG.md                # Version history
│
├── .claude-plugin/             # Claude Code entry point
│   └── instructions.md
├── .cursor-plugin/             # Cursor IDE entry point
│   └── instructions.md
├── .codex/                     # OpenAI Codex entry point
│   └── instructions.md
├── .opencode/                  # OpenCode entry point
│   └── instructions.md
│
├── skills/                     # Installable skill packs
│   ├── README.md               # Human-facing skill catalog
│   ├── SKILLS_INDEX.md         # Lightweight agent skill index
│   ├── kilo-kit/               # Core Kilo-Kit skills
│   │   ├── _template/          # Skill template
│   │   ├── debugging/          # Debugging skills
│   │   ├── development/        # Development skills
│   │   └── quality/            # Quality assurance skills
│   ├── engineering/            # Engineering and framework skills
│   ├── productivity/           # Agent workflow skills
│   ├── problem-solving/        # Debugging/reasoning skills
│   ├── design/                 # UI/design skills
│   └── ...                     # Games, ops, docs, AI media, security
│
├── commands/                   # Workflow commands
│   ├── quality-gate.md         # Quality gate workflow
│   ├── init-skill.md           # Skill initialization
│   └── validate-skill.md       # Skill validation
│
├── src/                        # Core system source
│   ├── core/                   # Core system components
│   │   ├── KILO_MASTER.md     # Master skill file (entry point)
│   │   ├── predictive-engine/  # Predictive Context Engine
│   │   ├── routing-engine/     # Adaptive Routing Engine
│   │   ├── execution-engine/   # Execution & Quality Gates
│   │   └── knowledge-layer/    # Persistent Knowledge
│   │
│   ├── behaviors/              # Composable Behavior Units
│   │   ├── atomic/             # Smallest behavior units
│   │   ├── compound/           # Combined behaviors
│   │   └── meta/               # Meta-behaviors
│   │
│   └── tools/                  # CLI and utility tools
│       ├── init-skill.py       # Skill initializer
│       ├── validate-skill.py   # Skill validator (Python)
│       └── validate-skill.js   # Skill validator (Node.js)
│
├── docs/                       # Documentation
│   ├── architecture/           # Architecture decisions
│   ├── COMPLETION_ASSESSMENT.md
│   ├── DEEP_ANALYSIS.md
│   └── PROJECT_STRUCTURE.md
│
└── examples/                   # Real-world examples
    ├── basic/                  # Basic usage patterns
    ├── intermediate/           # Intermediate patterns
    └── advanced/               # Advanced patterns

🚀 Quick Start

1. Install

# Clone the repository
git clone https://github.com/VoDaiLocz/KILO-KIT.git
cd kilo-kit

# No dependencies required - works out of the box!

2. Configure Your Agent

Copy the master skill file to your agent's configuration:

# For most AI agents
cp src/core/KILO_MASTER.md ~/.your-agent/KILO_MASTER.md

# Update your agent's system prompt to reference it

3. Use Skills

Skills are automatically loaded when your task matches their keywords. See the Skill Dispatch Table below.

📋 Skill Dispatch Table

🎓 Core Principles

1. Cognitive Flow Architecture

Traditional:  Task → Process → Response (done)

Kilo-Kit:     ┌─────────────────────────────┐
              │      COGNITIVE FLOW         │
              │                             │
    Input ───►│  Predict → Execute → Learn  │───► Output
              │      ↑              │       │
    Next  ───►│      └──────────────┘       │───► Better
              │                             │
              └─────────────────────────────┘

2. Quality Gates (NEVER SKIP)

# Before EVERY commit
typecheck → lint → test → build

# All must pass. No exceptions.

3. The Three Pillars

ANTICIPATE → EXECUTE → LEARN → OPTIMIZE
     ↑                            │
     └────────────────────────────┘

4. Progressive Disclosure

Level 1: Metadata (always loaded, ~100 tokens)
Level 2: SKILL.md body (when triggered, <5k tokens)  
Level 3: References/Scripts (on-demand, unlimited)

🔧 Creating Custom Skills

Use the skill template:

python src/tools/init-skill.py my-skill --path ./skills/kilo-kit/

This creates:

my-skill/
├── SKILL.md           # Main instructions (required)
├── references/        # Documentation to load as needed
├── scripts/           # Executable utilities
└── assets/            # Templates, images, etc.

SKILL.md Format

---
name: my-skill
description: >-
  Clear description of what this skill does and when to use it.
  Include keywords that should trigger this skill.
version: 1.0.0
behaviors: [behavior1, behavior2]
token_estimate:
  min: 500
  typical: 1500
  max: 5000
---

# My Skill

## When to Use
- Situation 1
- Situation 2

## Process
1. Step 1
2. Step 2

## Guidelines
- Guideline 1
- Guideline 2

## References
- `references/detailed-guide.md` - For detailed instructions
- `scripts/helper.py` - For automated tasks

📚 Documentation

• QUICKSTART.md - Get started in 15 minutes
• docs/architecture/ - Architecture design documents
• docs/PROJECT_STRUCTURE.md - Project structure guide
• examples/ - Real-world usage examples

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for:

• Code of conduct
• Development setup
• Pull request process
• Coding standards

📊 Stack Preferences

TypeScript/JavaScript (2024-2025)

Python

.NET

🏗️ Roadmap

• v1.0.0 - Core Cognitive Flow Architecture
• v1.1.0 - MCP Integration
• v1.2.0 - Multi-Agent Orchestration
• v2.0.0 - Visual Workflow Builder

📄 License

Apache 2.0 - See LICENSE for details.

Made with ❤️ for developers who value quality, efficiency, and scalability.

Kilo-Kit — Where AI meets excellence.