at Language Agent Skill

Description

--- name: at-language-expert description: Essential procedural knowledge and constraints for writing, debugging, and understanding the `at` programming language. --- # `at` Language Agent Skill This skill provides the mandatory procedural knowledge required to successfully write and debug `at` code. `at` is a fast, strictly-typed language built specifically for AI agents. ## Design Philosophy `at` is designed around what makes agents succeed, informed by [A Language For Agents](https://lucumr.pocoo.org/2026/2/9/a-language-for-agents/): - **Context without LSP:** Types are explicit in function signatures and return types. You never need an LSP to understand what a function accepts or returns. Local variables use inference to save tokens, but the public API is always readable. - **Braces over whitespace:** `at` uses `{ }` delimiters, not significant whitespace. This avoids the token-efficiency and surgical-edit problems that LLMs have with indentation-sensitive languages. - **Results over exceptions:** Prefer `Result<T, E>` and `?` propagation. `try/catch/finally` exists as an escape hatch but `Result` is the idiomatic error-handling pattern. Agents should default to returning `Result` types. - **Explicit effects:** Side effects (network, filesystem, time, randomness) must be declared via `needs { ... }` blocks. This makes mocking trivial in tests and gives agents clear signals about what a function touches. - **Minimal diffs:** Trailing commas are supported everywhere (arrays, maps, match arms, function params). Format code vertically to keep diffs single-line. - **Greppable imports:** All imports require aliasing (`import "x" as y;`). Every symbol use is prefixed with its module name (like Go's `context.Context`), making code searchable with basic tools like `grep` or `sed`. - **Local reasoning:** Each file is self-contained. No implicit globals, no re-exports, no barrel files. If you read a file, you can understand it without loading other files. - **No macros:** `at` has no macro system. Code generation is unnecessary when the cost of writing code is low. - **No re-exports or barrel files:** Every import points to the file that defines the symbol. One-to-one mapping from declaration to usage. - **Dependency-aware builds:** No circular imports. Packages have clear boundaries. Test results are aggressively cached. - **Deterministic tests:** Tests can pin time and randomness (`using time.fixed; using rand.seeded;`), eliminating flakiness by design. - **Single failure condition:** `at check` type-checks and lints in one pass. Code either passes or fails — there is no "compiles but has type errors" state. `at test` runs all tests. Two commands, zero ambiguity. ## Critical Constraints (Read First) 1. **Explicit Return Types Required:** Every function MUST declare its return type `fn name() -> type {`. 2. **Mandatory Import Aliasing:** You MUST alias all imports (`import "./utils.at" as utils;`). There are no global imports, no re-exports. 3. **Capability Sandboxing:** If a script touches the network, filesystem, or time, you MUST declare a `needs { ... }` block. 4. **Token Efficiency:** The compiler infers local variables. Use `let x = 5;` instead of `let x: int = 5;` to save tokens. 5. **Mutation uses `set`:** Variables are immutable by default. Use `set x = newValue;` to mutate (not `let mut`). 6. **Semicolons required:** All statements end with `;`. 7. **Match arms use commas:** Match arms are separated by `,` (not newlines). 8. **No macros:** There is no macro system. Write explicit code. 9. **Prefer `Result` over `try/catch`:** Use `Result<T, E>` and `?` for error handling. Avoid `try/catch` unless wrapping FFI or legacy code. ## 1. Syntax Overview ### Variables & Types ```at let immutable = 10; let mutable = 20; set mutable = 30; // `set` for mutation, not `let mut` // Type inference handles these automatically let array = [1, 2, 3]; let empty = []; // empty array literal let m = map {}; // empty map literal let m2 = map { "key": "value" }; ``` ### Functions & Tests Tests are colocated and execute at highly-optimized speeds with `at test`. ```at fn add(a: int, b: int) -> int { return a + b; } test "adds numbers" { assert(add(1, 2) == 3); } ``` ### Control Flow ```at if a > b { // ... } else { // ... } for item in array { // ... } while condition { // ... } ``` ### Error Handling Use `Result<T, E>` and `?` for early returns. This is the idiomatic pattern — agents should default to this over `try/catch`. ```at fn divide(a: int, b: int) -> Result<int, string> { if b == 0 { return Err("Division by zero"); } return Ok(a / b); } fn calculate() -> Result<int, string> { let result = divide(10, 2)?; return Ok(result + 1); } ``` ### Enums & Pattern Matching ```at enum Shape { Circle(float), Rect(float, float), // multi-field variants supported Point, // no-payload variant } fn area(s: Shape) -> float { return match s { Shape::Circle(r) => 3.14159 * r * r, Shape::Rect(w, h) => w * h, Shape::Point => 0.0, }; } ``` ### Higher-Order Functions `map`, `filter`, and `reduce` are compiler-inlined (not regular builtins): ```at let nums = [1, 2, 3, 4, 5]; let doubled = map(nums, |x| x * 2); let evens = filter(nums, |x| x % 2 == 0); let total = reduce(nums, 0, |acc, x| acc + x); ``` ## 2. Builtins Reference ### Core `print(value)`, `assert(condition)`, `assert_eq(a, b)`, `len(collection)`, `type_of(value)` ### Math `abs(n)`, `min(a, b)`, `max(a, b)`, `floor(f)`, `ceil(f)`, `round(f)`, `pow(base, exp)`, `sqrt(f)`, `sum(array)` ### String `contains(haystack, needle)` (works on arrays and strings), `slice(arr, start, end)`, `split(str, delim)`, `trim(str)`, `to_upper(str)`, `to_lower(str)`, `substring(str, start, end)`, `join(array, sep)`, `replace(str, old, new)`, `starts_with(str, prefix)`, `ends_with(str, suffix)`, `repeat(str, n)`, `parse_int(str)`, `parse_float(str)`, `to_string(value)` ### Character `char_code(str)`, `from_char_code(n)`, `is_digit(str)`, `is_alpha(str)`, `is_upper(str)`, `is_lower(str)` ### Array `append(arr, value)`, `sort(arr)`, `reverse(arr)`, `index_of(arr, value)`, `count(arr, value)`, `range(start, end)` ### Map `keys(map)`, `values(map)` ### Regex `regex_match(str, pattern)` -> `bool`, `regex_find(str, pattern)` -> `array<string>`, `regex_replace(str, pattern, replacement)` -> `string` Note: Use `{{` to escape literal `{` in regex patterns inside string literals (e.g., `"[0-9]{{3}}"` for the regex `[0-9]{3}`). ### Option & Result `some(v)`, `none()`, `is_some(opt)`, `is_none(opt)`, `ok(v)`, `err(v)`, `is_ok(res)`, `is_err(res)` ## 3. Explicit Effects & Sandboxing Agents execute in a secure sandbox. You cannot perform side-effects without declaring them statically. ```at needs { network, fs } // MUST be declared if you fetch or read files import "std/http.at" as http; fn fetch_data() -> Result<string, string> { return http.get("https://example.com"); } ``` For test determinism, declare deterministic environments: ```at using time.fixed; using rand.seeded; ``` ## 4. Code Generation Checklist for LLMs Before modifying or generating `at` code, verify: - [ ] **Mutation**: Use `set x = value;` to mutate, not `let mut`. - [ ] **Error handling**: Use `Result<T, E>` and `?`, not `try/catch`. - [ ] **Formatting**: Multi-element arrays, tuples, and maps MUST be formatted vertically to preserve diff-stable trailing commas. - [ ] **Aliasing**: Did you alias all imports? (`import "x" as y;`) - [ ] **Effects**: Did you declare `needs { ... }` at the top of the file if accessing external systems? - [ ] **Tests**: Are you writing colocated `test "name" { assert(...); }` blocks for your functions? - [ ] **Types**: Did you let the compiler infer types for local variables using `let x = ...`? - [ ] **Semicolons**: All statements end with `;`. - [ ] **Match commas**: Match arms separated by `,`. - [ ] **Mixed arithmetic**: `int` and `float` can be mixed freely (int is promoted to float). - [ ] **No macros**: Write explicit code. There is no macro system. - [ ] **Local reasoning**: Each file should be self-contained. No re-exports, no barrel files. ## 5. Development CLI As an agent, you can use these tools to iteratively validate your code: - `at check` - Type-check and lint in one pass (instant, catches all errors before runtime) - `at test <file|dir>` - Run tests in a file or recursively in a directory (aggressively cached, very fast feedback loop) - `at run <file>` - Execute a script - `at fix` - Auto-formats code and fixes lints ## 6. Limitations These are things `at` intentionally does not support or has not yet implemented: - **No classes or inheritance.** Only structs and enums (algebraic data types). - **No mutable references.** All data is immutable/copy-on-write (`Rc`-shared). `set` creates new copies. - **No standard I/O beyond `print`.** No `read_line`, no file I/O builtins (would require `fs` capability and corresponding builtins which do not exist yet). - **No hash/set data structure.** Only arrays and ordered maps. Use a map with dummy values as a workaround. - **No package manager.** Remote imports are direct URL fetches with caching. - **No null.** Uses `option` (`some`/`none`) instead. - **No implicit returns.** Must use `return` keyword (though block expressions have implicit tail values). - **Integer arithmetic is overflow-checked.** Large computations will error rather than wrap. - **Single-threaded.** Async is cooperative, not parallel. No OS-level threading. - **No recursion depth guarantees.** A configurable `max_frames` limit exists for sandboxed execution. - **String interpolation uses `{expr}`.** Use `{{` to write a literal `{` in strings (relevant for regex patterns with quantifiers like `{3}`).

Security Status