# Kagent Dev

Development guide for kagent's v1alpha3 Harness and AgentTemplate CRDs, Session gRPC...

- Repository: https://github.com/kagent-dev/kagent (4134 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kagent-dev/kagent --skill kagent-dev -g -a claude-code -y`
Codex: `npx skills add kagent-dev/kagent --skill kagent-dev -g -a codex -y`
Cursor: `npx skills add kagent-dev/kagent --skill kagent-dev -g -a cursor -y`
Gemini CLI: `npx skills add kagent-dev/kagent --skill kagent-dev -g -a gemini-cli -y`

## Description

Development guide for kagent's v1alpha3 Harness and AgentTemplate CRDs, Session gRPC control plane, upstream A2A integration, Substrate runtime provisioning, tests, generation, and PR workflow. Use for any implementation, debugging, review, or CI task in the kagent repository.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# kagent development guide

Use `docs/architecture` and the current implementation to understand component boundaries. Keep each PR focused on the requested change and its necessary dependencies.

Read the root [AGENTS.md](../../../AGENTS.md) and applicable nested guides before
editing. Directory-specific validation, persistence, transport, and UI rules live
there; use this skill for development workflows and the remaining specialized guidance.

## Architecture

- `Agent`, `Harness`, and `AgentTemplate` are `api.kagent.dev/v1alpha3` CRDs under `go/api/v1alpha3`.
- `Session` is stored in PostgreSQL and exposed through gRPC, not Kubernetes.
- Upstream A2A owns public interaction and history semantics.
- Substrate Actors are the only runtime compute path.
- DurableDir owns private runtime state needed across lifecycle operations and snapshots.
- kagent, Codex, and Claude are release-blocking Harness adapters.

The public API must not acquire Kubernetes scheduling, service-account, workload deployment, arbitrary runtime-container, channel, profile, or generic extension fields.

## Repository map

```text
go/api/v1alpha3/                 CRD types and validation
helm/kagent-crds/templates/      generated CRDs and Helm packaging
proto/                           protobuf and Buf inputs
go/api/gen/                      generated Go protobuf code
go/core/internal/grpcserver/     gRPC transport and policy
go/core/internal/service/        transport-independent services
go/core/internal/database/       Inline pgx SQL and private typed rows
go/core/pkg/migrations/          PostgreSQL migrations
go/core/internal/controller/     CRD reconciliation and preparation
go/adk/                          Go runtime
python/packages/                 Python runtime packages
ui/                              static Vite browser UI
helm/                            installation charts
```

## Workflow

The rest: https://github.com/kagent-dev/kagent/blob/HEAD/.agents/skills/kagent-dev/SKILL.md