Skip to content
Skein

Agent Quick Reference

Project Identity

Section titled “Project Identity”

Skein is a programming language that compiles to BEAM bytecode and runs on the Erlang VM (OTP). The compiler and toolchain are implemented in Elixir. Skein is designed for building cloud services where AI agents are first-class constructs.

Repository Structure

Section titled “Repository Structure”
skein/
├── mix.exs                      # Root umbrella project
├── CLAUDE.md                    # Agent instructions
├── .docs-config.json            # Documentation site config
├── docs/
│   ├── SKEIN_SPEC.md            # Complete language specification
│   ├── ARCHITECTURE.md          # Compiler and runtime architecture
│   ├── ROADMAP.md               # Development roadmap
│   └── site/                    # Astro + Starlight documentation site
├── editors/
│   └── vscode/                  # VS Code extension (grammar, snippets, LSP client)
├── apps/
│   ├── skein_compiler/          # Lexer, parser, analyzer, code generator
│   ├── skein_runtime/           # OTP behaviours and runtime support
│   ├── skein_cli/               # CLI tooling
│   └── skein_lsp/               # Language Server Protocol implementation
└── examples/                    # Canonical .skein programs

Technology Stack

Section titled “Technology Stack”
ComponentChoice
Compiler languageElixir
LexerHand-written binary matching
ParserHand-written recursive descent
IR targetCore Erlang
Agent runtimeOTP’s :gen_statem (used directly)
HTTP serverBandit + Plug
StorageEcto + SQLite3
Language serverGenLSP
TestingExUnit + StreamData + PropCheck

Commands

Section titled “Commands”
CommandPurpose
mix deps.getInstall dependencies
mix compileCompile the compiler
mix testRun all tests
mix formatFormat code

Compilation Pipeline

Section titled “Compilation Pipeline”

Source (.skein) → Lexer → Parser → Analyzer → CodeGen → BEAM bytecode

  1. Lexer (Skein.Lexer) — source text to token stream
  2. Parser (Skein.Parser) — token stream to AST
  3. Analyzer (Skein.Analyzer) — AST to annotated AST (multi-pass: name resolution, type checking, capability checking, transition checking, plus lint passes for unused bindings/capabilities and unreachable code)
  4. CodeGen (Skein.CodeGen.CoreErlang) — AST to Core Erlang to BEAM bytecode

Key Modules

Section titled “Key Modules”

Compiler

Section titled “Compiler”
ModuleLocationPurpose
Skein.Lexerapps/skein_compiler/lib/skein/lexer.exTokenizer
Skein.Parserapps/skein_compiler/lib/skein/parser.exAST construction
Skein.ASTapps/skein_compiler/lib/skein/ast.exAST node definitions
Skein.Analyzerapps/skein_compiler/lib/skein/analyzer.exType + capability checking
Skein.CodeGen.CoreErlangapps/skein_compiler/lib/skein/codegen/core_erlang.exCode generation
Skein.CodeGen.SchemaGenapps/skein_compiler/lib/skein/codegen/schema_gen.exJSON Schema derivation
Skein.Errorapps/skein_compiler/lib/skein/error.exStructured error types
Skein.Compilerapps/skein_compiler/lib/skein_compiler.exPipeline entry point

Runtime

Section titled “Runtime”
ModuleLocationPurpose
Skein.Runtime.Agentapps/skein_runtime/lib/skein/runtime/agent.ex:gen_statem-based agent lifecycle
Skein.Runtime.Httpapps/skein_runtime/lib/skein/runtime/http.exHTTP client with capability enforcement
Skein.Runtime.Capabilityapps/skein_runtime/lib/skein/runtime/capability.exRuntime capability validation
Skein.Runtime.Handlerapps/skein_runtime/lib/skein/runtime/handler.exHTTP request dispatch
Skein.Runtime.Storeapps/skein_runtime/lib/skein/runtime/store.exETS-backed storage (default)
Skein.Runtime.StoreEctoapps/skein_runtime/lib/skein/runtime/store_ecto.exEcto/SQLite-backed storage
Skein.Runtime.EctoSchemaapps/skein_runtime/lib/skein/runtime/ecto_schema.exDynamic Ecto schema generation
Skein.Runtime.MigrationGenapps/skein_runtime/lib/skein/runtime/migration_gen.exEcto migration generation
Skein.Runtime.Repoapps/skein_runtime/lib/skein/runtime/repo.exEcto Repo (SQLite3)
Skein.Runtime.Memoryapps/skein_runtime/lib/skein/runtime/memory.exScoped KV memory
Skein.Runtime.Llmapps/skein_runtime/lib/skein/runtime/llm.exLLM client with schema-constrained JSON
Skein.Runtime.Serverapps/skein_runtime/lib/skein/runtime/server.exHTTP server
Skein.Runtime.Traceapps/skein_runtime/lib/skein/runtime/trace.exTrace span recording

Language Server

Section titled “Language Server”
ModuleLocationPurpose
Skein.Lsp.Serverapps/skein_lsp/lib/skein/lsp/server.exMain LSP server
Skein.Lsp.Diagnosticsapps/skein_lsp/lib/skein/lsp/diagnostics.exCompiler error → LSP diagnostic
Skein.Lsp.Symbolsapps/skein_lsp/lib/skein/lsp/symbols.exDocument symbol extraction
Skein.Lsp.HoverProviderapps/skein_lsp/lib/skein/lsp/hover_provider.exHover info and go-to-definition
Skein.Lsp.Completionsapps/skein_lsp/lib/skein/lsp/completions.exContext-aware code completion
Skein.Lsp.SemanticTokensapps/skein_lsp/lib/skein/lsp/semantic_tokens.exSemantic token encoding

Coding Conventions

Section titled “Coding Conventions”
  • Follow mix format style
  • Typespecs (@spec) on all public functions
  • @moduledoc and @doc on all public modules and functions
  • Pattern match in function heads over case/cond
  • Pipe operator for data transformations
  • {:ok, result} / {:error, errors} tuples throughout the pipeline
  • TDD is mandatory — tests before or alongside implementation

Error Format

Section titled “Error Format”

Every compiler error is a %Skein.Error{} struct with fields: code, severity, message, location, context, fix_hint, fix_code. Errors serialize to JSON.

Terminology

Section titled “Terminology”
Canonical TermDo Not Use
agentbot, assistant
moduleclass, package
handlerendpoint, route
phasestate, stage
capabilitypermission, privilege

Current Status

Section titled “Current Status”

All phases complete — MVP reached. The full compilation pipeline supports:

  • Modules with functions, let bindings, match expressions, pipes, string interpolation
  • Type checking with inference, JSON schema derivation, constraint annotations
  • Capability-based security with compile-time and runtime enforcement
  • HTTP/queue/schedule handlers with route matching and path parameters
  • ETS-backed store operations with capability gating and typed tables (C5, #255) — capability store.table("users", User) names the record type, operations are type-checked, writes are schema-checked at runtime (the Ecto/SQLite path remains unwired library code)
  • Agent state machines with phase transitions, compile-time transition validation
  • Scoped KV memory with namespace isolation
  • LLM client with pluggable backends, schema-validated JSON decoding for llm.json[T] (responses are recursively validated against the derived schema — C3, #298; violations are Err(LlmError.InvalidSchema(violations))), and streaming
  • Automatic trace recording for all effect calls
  • Full CLI tooling (new, build, test, run, trace)
  • VS Code extension with LSP (diagnostics, symbols, hover, completions, go-to-definition)

Test suite: the full umbrella unit and property suites run green — see CI for current counts