Skip to content
Skills Library
Programming · Building & coding

kagent-dev

/kagent-dev

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.

Repository
kagent ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Original author 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.

How it works

  1. Architecture
  2. Repository map
  3. Workflow
  4. CRD changes
  5. Protobuf changes
  6. Database changes
  7. Authorization changes
  8. Testing and CI
  9. PR discipline
Original SKILL.md headings · 119 lines, 844 words
SKILL.md preview
---
name: kagent-dev
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.
---

# 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

1. Read the relevant architecture docs and trace existing callers before editing.
2. Before adding a helper or public function, search for an equivalent in the owning package and its callers; reuse existing transport and credential paths when they fit. Keep model credentials as Secret references, not plaintext ModelConfig or serialized agent fields; Substrate injects them at the egress gateway.
3. Keep generated code generated; edit source types, protobufs, SQL, or templates first.
4. Add the smallest check that proves new behavior. Tests tied only to removed APIs should be deleted rather than translated.
5. Run focused tests first, then the relevant repository checks.

Useful commands:

```bash
make controller-manifests   # deepcopy and CRDs in the Helm chart
make proto-lint proto-generate proto-breaking
make -C go test
make -C go lint
make -C python lint
```

For SQL and store changes, follow [database guidance](../../../go/core/internal/database/AGENTS.md), including the PostgreSQL statement-preparation check.

## CRD changes

- Follow [Kubernetes API conventions](../../../docs/kubernetes-api.md) for field presence, validation markers, and unions.
- Modify only the intended v1alpha3 type and its validation.
- Use explicit typed fields; avoid extension maps and speculative options.
- Regenerate deepcopy code, Helm-packaged CRDs, and RBAC when affected.
- Verify generated schemas contain the intended fields and omit forbidden runtime infrastructure fields.

## Protobuf changes

Follow [protobuf guidance](../../../proto/AGENTS.md) for validation, upstream schemas,
generation, and compatibility checks. When implementing an RPC, also read
[gRPC transport guidance](../../../go/core/internal/grpcserver/AGENTS.md).
Add generated contracts before registering implementations when the roadmap separates those PRs.

## Database changes

- PostgreSQL migrations use Goose with embedded SQL files.
- Add each migration as `NNNNNN_description.sql`.
- Do not add legacy split files ending in `.up.sql` or `.down.sql`.
- Include one `-- +goose Up` section and one `-- +goose Down` section.
- Goose makes the Down section optional, but Kagent requires it for the database CLI.
- Do not use `-- +goose NO TRANSACTION`.
- Goose must commit each schema change and its migration record in one transaction.
- Never change, rename, or delete a migration after it merges.
- Fix an accepted migration with a new migration.
- Keep migration SQL schema-agnostic.
- Change only objects that the migration source owns.
- Do not use existence guards for source-owned objects; a migration ledger mismatch must fail.
- Use existence guards only for shared bootstrap resources such as PostgreSQL extensions.
- Each migration source must use its own migration table and advisory lock.
- Register dependent sources after the sources that they need.
- Do not add automatic down migrations when a later source fails.
- A restart must continue from each source's last committed version.
- Allow non-destructive startup when the database is ahead of the binary for rolling compatibility.
- The Goose cutover requires a fresh PostgreSQL database.
- Do not add a golang-migrate bridge for the cutover.
- Keep `schema_migrations` for the core source.
- Keep `vector_schema_migrations` for the vector source.
- Run the PostgreSQL store tests after a migration change to validate every inline statement against the new schema.
- Test the Up and Down sections against PostgreSQL.
- Use PostgreSQL constraints for invariants that the database can enforce atomically.

## Authorization changes

For resource or collection authorization work, read the [scoped authorization guide](references/scoped-authorization.md) before changing services or list queries.

## Testing and CI

- Focused unit and generation checks are required for implemented behavior.
- Clean-install coverage is authoritative during the API transition.
- Substrate end-to-end coverage may remain non-blocking until the final conformance milestone, but the final release requires it.
- Do not spend time preserving tests whose sole subject no longer exists.

## PR discipline

- Follow the roadmap dependency graph.
- Keep Codex and Claude adapter work in separate PRs consuming the same resolved-bundle boundary.
- Avoid concurrent ownership of protobuf registration, migrations, controller wiring, or generated CRDs.
- Use Conventional Commits and sign commits with `-s`.
Files in this package (2)
  • SKILL.md 7 KB
  • references/scoped-authorization.md 5 KB

Versions

The database has no other skills named kagent-dev.

Database snapshot: 13.11.2026 · package version e5346bc189df (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100kagent
    Use kagent agents and standalone sandboxes. Use when configuring, invoking, sharing, or troubleshooting kagent agents, or using available kagent sandboxes as temporary workspaces to run scripts, test code, process files, and collect artifacts for an agent's own tasks.
  • 100kagent
    Expert guide for kagent — the open-source CNCF framework for building, deploying, and running AI agents on Kubernetes. Covers the kagent CLI, declarative and BYO agents (Agent, SandboxAgent, ModelConfig, RemoteMCPServer, MCPServer CRDs), LLM provider setup, MCP and HTTP tools,…
  • 100architecture-flow-docs
    Write or update a kagent architecture page that explains an end-to-end flow, such as creating an Agent or sending a message, with an Excalidraw diagram of the components involved. Use when documenting a flow in docs/architecture or when an architecture change makes such a page out of date.
  • 100grpc
    gRPC and Protocol Buffers skill. Proto design, code generation, streaming patterns, gRPC-web, load balancing, service mesh integration. Triggers on: /godmode:grpc, "gRPC service", "proto file", "streaming RPC", "gRPC-web".
  • 100grpc-service-generator
    Generate grpc service generator operations. Auto-activating skill for Backend Development. Triggers on: grpc service generator, grpc service generator Part of the Backend Development skill category. Use when working with grpc service generator functionality. Trigger with phrases…
  • 100ark-controller-development
    Guidance for developing the Ark Kubernetes operator. Use when modifying Go types, CRDs, controllers, or webhooks. Helps with CRD generation and Helm chart sync issues.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.