llms.txt

# Skelegent

> 6-layer composable agentic AI runtime in Rust.

Skelegent is a Rust framework for building agentic AI systems. It decomposes
the problem into six architectural layers (Layer 0 through Layer 5), each with clear trait
boundaries, so every concern — from protocol serialization to secret
management — lives in exactly one place.

## Getting Started

- [README.md](README.md) — project overview and quickstart
- [ARCHITECTURE.md](ARCHITECTURE.md) — layered architecture summary
- [SPECS.md](SPECS.md) — spec index and status
- [CONTRIBUTING.md](CONTRIBUTING.md) — contribution guidelines

### Build

Skelegent builds inside a Nix devshell:

```sh
nix develop --command cargo test --workspace --all-targets
nix develop --command cargo clippy --workspace --all-targets -- -D warnings
nix develop --command cargo doc --workspace --no-deps
```

## Reading Order

1. [ARCHITECTURE.md](ARCHITECTURE.md)
2. [SPECS.md](SPECS.md)
3. [specs/00-vision-and-non-goals.md](specs/00-vision-and-non-goals.md)
4. [specs/01-architecture-and-layering.md](specs/01-architecture-and-layering.md)
5. [docs/book/src/architecture/layers.md](docs/book/src/architecture/layers.md)
6. [docs/book/src/architecture/protocol-traits.md](docs/book/src/architecture/protocol-traits.md)

## Architecture

- [docs/architecture/orchestrator-composition-guide.md](docs/architecture/orchestrator-composition-guide.md) — orchestrator composition patterns

## Specs

| #  | Spec | Path |
|----|------|------|
| 00 | Vision and Non-Goals | [specs/00-vision-and-non-goals.md](specs/00-vision-and-non-goals.md) |
| 01 | Architecture and Layering | [specs/01-architecture-and-layering.md](specs/01-architecture-and-layering.md) |
| 02 | Layer 0 Protocol Contract | [specs/02-layer0-protocol-contract.md](specs/02-layer0-protocol-contract.md) |
| 03 | Effects and Execution Semantics | [specs/03-effects-and-execution-semantics.md](specs/03-effects-and-execution-semantics.md) |
| 04 | Operator Turn Runtime | [specs/04-operator-turn-runtime.md](specs/04-operator-turn-runtime.md) |
| 05 | Orchestration Core | [specs/05-orchestration-core.md](specs/05-orchestration-core.md) |
| 06 | Composition, Factory, and Glue | [specs/06-composition-factory-and-glue.md](specs/06-composition-factory-and-glue.md) |
| 07 | State Core | [specs/07-state-core.md](specs/07-state-core.md) |
| 08 | Environment and Credentials | [specs/08-environment-and-credentials.md](specs/08-environment-and-credentials.md) |
| 09 | Hooks Lifecycle and Governance | [specs/09-hooks-lifecycle-and-governance.md](specs/09-hooks-lifecycle-and-governance.md) |
| 10 | Secrets, Auth, Crypto | [specs/10-secrets-auth-crypto.md](specs/10-secrets-auth-crypto.md) |
| 11 | Testing, Examples, and Backpressure | [specs/11-testing-examples-and-backpressure.md](specs/11-testing-examples-and-backpressure.md) |
| 12 | Packaging, Versioning, and Umbrella Crate | [specs/12-packaging-versioning-and-umbrella-crate.md](specs/12-packaging-versioning-and-umbrella-crate.md) |
| 13 | Documentation and DX Parity | [specs/13-documentation-and-dx-parity.md](specs/13-documentation-and-dx-parity.md) |

## Key Concepts

- **OperatorId** — typed identity for operators (protocol-level concept)
- **Operator** — object-safe trait: `async fn execute(input, orch) -> Result<Output, Error>`
- **Orchestrator** — dispatches to operators by ID; `dispatch()` and `dispatch_many()`
- **StateStore** — object-safe key-value state with scopes, hints, and text search
- **Context** — mutable conversation context with ops, rules, and metrics
- **Rule** — reactive `ContextOp` with triggers (before/after/when) for automated behavior
- **Provider** — NOT object-safe; generic `<P: Provider>` everywhere, erased at `Operator` boundary
- **Effect** — declarative side-effects emitted by operators (Delegate, Handoff, Log, etc.)
- **Scope** — where state lives: Session, Workflow, Operator, Global, Custom

## Crate Map

### Layer 0 — Protocol

| Crate | Path |
|-------|------|
| layer0 | [layer0/](layer0/) |

### Layer 1 — Turn Runtime

| Crate | Path |
|-------|------|
| skg-turn | [turn/skg-turn](turn/skg-turn/) |
| skg-context | [turn/skg-context](turn/skg-context/) |
| skg-tool | [turn/skg-tool](turn/skg-tool/) |
| skg-tool-macro | [turn/skg-tool-macro](turn/skg-tool-macro/) |
| skg-mcp | [turn/skg-mcp](turn/skg-mcp/) |
| skg-turn-kit | [turn/skg-turn-kit](turn/skg-turn-kit/) |

### Layer 1 — Operators

| Crate | Path |
|-------|------|
| skg-context-engine | [op/skg-context-engine](op/skg-context-engine/) |
| skg-op-single-shot | [op/skg-op-single-shot](op/skg-op-single-shot/) |

### Layer 1 — Providers

| Crate | Path |
|-------|------|
| skg-provider-anthropic | [provider/skg-provider-anthropic](provider/skg-provider-anthropic/) |
| skg-provider-openai | [provider/skg-provider-openai](provider/skg-provider-openai/) |
| skg-provider-ollama | [provider/skg-provider-ollama](provider/skg-provider-ollama/) |
| skg-provider-codex | [provider/skg-provider-codex](provider/skg-provider-codex/) |

### Layer 2 — Orchestration

| Crate | Path |
|-------|------|
| skg-orch-local | [orch/skg-orch-local](orch/skg-orch-local/) |
| skg-orch-kit | [orch/skg-orch-kit](orch/skg-orch-kit/) |

### Layer 2 — Effects

| Crate | Path |
|-------|------|
| skg-effects-core | [effects/skg-effects-core](effects/skg-effects-core/) |
| skg-effects-local | [effects/skg-effects-local](effects/skg-effects-local/) |

### Layer 3 — State

| Crate | Path |
|-------|------|
| skg-state-memory | [state/skg-state-memory](state/skg-state-memory/) |
| skg-state-fs | [state/skg-state-fs](state/skg-state-fs/) |

### Layer 4 — Environment

| Crate | Path |
|-------|------|
| skg-env-local | [env/skg-env-local](env/skg-env-local/) |
| skg-secret | [secret/skg-secret](secret/skg-secret/) |
| skg-secret-vault | [secret/skg-secret-vault](secret/skg-secret-vault/) |
| skg-auth | [auth/skg-auth](auth/skg-auth/) |
| skg-crypto | [crypto/skg-crypto](crypto/skg-crypto/) |

### Layer 5 — Cross-cutting (Hooks)

| Crate | Path |
|-------|------|
| skg-hook-security | [hooks/skg-hook-security](hooks/skg-hook-security/) |

### Umbrella

| Crate | Path |
|-------|------|
| skelegent | [skelegent/](skelegent/) |

### Testing

| Crate | Path |
|-------|------|
| test-utils | [test-utils/](test-utils/) |

### Examples

| Example | Path |
|---------|------|
| custom_operator_barrier | [examples/custom_operator_barrier](examples/custom_operator_barrier/) |