sky AGENTS.md

AGENTS.md

Agent-agnostic guide for AI tools (Claude, Copilot, Cursor, Codex, …) working in the Sky repository. It is the source of truth; tool-specific files layer on top of it (Claude Code reads CLAUDE.md, which imports this file and adds Claude-Code-only operational rules).

Progressive disclosure. This file is deliberately lean. It teaches the language, the app-building decisions, and the non-negotiable rules, then points you at two authoritative, always-current sources for depth:

• sky doc <Module> — the live stdlib API (typed signatures + summaries + examples), generated from the stdlib source, so it never drifts. Prefer it over any hand-copied API table. sky doc --list enumerates every module; sky doc --serve opens a browsable server.
• docs/ — deep dives (architecture, Sky.Live, Std.Db, Std.Ui, auth, tooling). The map is in the Deep dives table below.

What Sky is

Sky is an Elm-family, purely-functional language that compiles to typed Go. One language for the whole stack: web UIs (Sky.Live), HTTP/JSON APIs, CLIs, TUIs, desktop apps, background jobs. The design goal is "if it compiles, it works" — no user-written FFI, no nulls, no runtime panics from well-typed code, clear errors, batteries-included stdlib.

The compiler is the Rust rewrite (cargo workspace at rust/). The retired Haskell compiler lives under legacy-haskell-compiler/ and serves as a differential oracle (sky-out/sky) the Rust output is checked against byte-for-byte. Current line: v0.23.x.

Language essentials

Sky's surface is Elm. If your training on Elm is thin, read this section carefully — it is the part that catches models out.

module Main exposing (main)

import Sky.Core.Prelude exposing (..)      -- Result/Maybe/identity/… autoloaded
import Sky.Core.List as List
import Std.Log exposing (println)

type alias User = { name : String, age : Int }   -- record alias
type Msg = Increment | Decrement                 -- tagged union (ADT)

greet : User -> String                            -- type annotation (optional but preferred)
greet u =
    "Hi " ++ u.name

update : Msg -> Int -> Int
update msg count =
    case msg of                                   -- case is exhaustiveness-checked
        Increment -> count + 1
        Decrement -> count - 1

main =
    println (greet { name = "Ada", age = 40 })