# Gleam > Comprehensive Gleam skill covering language fundamentals, backend (OTP, Use when this capability is needed. - Skill: `tomevault-io/gleam` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/gleam` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/gleam/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/gleam --- # Gleam Best Practices Consolidated skill for Gleam development. Use decision trees below to find the right reference, then load detailed docs. ## Token Efficiency **All agents and commands using this skill MUST follow `references/token-efficiency.md`.** Use Grep and targeted reads instead of reading entire files. Start with `git diff` to scope work. ## Core Principles 1. **Errors as Values** — use Result types, never exceptions 2. **Explicit over Implicit** — no hidden state, no magic 3. **Type Safety** — let the compiler catch bugs 4. **Layered Architecture** — separate concerns 5. **Parse, Don't Validate** — opaque types for validated data ## Quick Decision Trees ### "I need to write Gleam code" Writing Gleam? ├─ New to syntax (no if, records, imports) → fundamentals/language-basics.md ├─ Case expressions, pattern matching → fundamentals/case-patterns.md ├─ Label shorthand, let assert, pipelines → fundamentals/language-features.md ├─ Useful stdlib functions → fundamentals/stdlib.md ├─ Module name mistakes (regexp/regex) → fundamentals/stdlib-module-names.md ├─ String character filtering (no \0) → fundamentals/string-character-filtering.md ├─ JSON decoding/encoding → fundamentals/decoding.md ├─ decode.map vs decode.then → fundamentals/decode-map-vs-then.md ├─ Opaque types, module design → fundamentals/type-design.md ├─ Error discipline, AppError patterns → fundamentals/error-handling.md ├─ use/result.try, helpers → fundamentals/code-patterns.md ├─ Helper-first refactoring → fundamentals/helper-first-refactoring.md ├─ Higher-order SQL helpers → fundamentals/higher-order-sql-helpers.md ├─ Tooling (gleam check, format, LSP) → fundamentals/tooling.md ├─ Input validation (valid) → fundamentals/validation-valid.md ├─ Parser combinators (nibble) → fundamentals/parsing-nibble.md ├─ Snapshot testing (birdie) → fundamentals/birdie-snapshot-testing.md ├─ Common mistakes → fundamentals/common-pitfalls.md └─ Official conventions & anti-patterns → fundamentals/conventions.md ### "I need to build a backend" Backend (Erlang target)? ├─ Web framework (wisp) → backend/wisp-framework.md ├─ HTTP server (mist) → backend/mist-server.md ├─ HTTP logging (single middleware) → backend/http-logging-middleware.md ├─ DB error handling (3-tier) → backend/three-tier-error-handling.md ├─ Decoder defaults anti-pattern → backend/decoder-defaults-anti-pattern.md ├─ OTP actors (basics, state, messages) → backend/otp.md ├─ OTP supervision (trees, strategies) → backend/otp-supervision.md ├─ OTP advanced (selectors, timers, ETS) → backend/otp-advanced.md ├─ Production logging (wisp) → Use /observability-master command ├─ HTTP client runner → backend/http-runner.md ├─ Midas algebraic effects → backend/midas-effect-task.md ├─ SQL code generation (Squirrel) → backend/squirrel-guide.md ├─ SQL code generation (Parrot/sqlc) → backend/parrot-guide.md ├─ Database migrations (Cigogne) → backend/cigogne.md ├─ JWT authentication (ywt) → backend/jwt-ywt.md ├─ S3 / object storage (bucket) → backend/bucket-s3.md ├─ Image processing (ansel) → backend/ansel-image.md ├─ PDF generation (paddlefish) → backend/paddlefish-pdf.md └─ Password hashing, timestamps → backend/auth.md ### "I need to build a frontend" Frontend (Lustre / JS target)? ├─ MVU architecture, state, messages → frontend/lustre-core.md ├─ Effects, paint-cycle, context → frontend/lustre-effects.md ├─ SPA routing (modem) → frontend/lustre-routing.md ├─ HTTP requests (rsvp) → frontend/lustre-http.md ├─ Web components, slots, CSS parts → frontend/lustre-components.md ├─ Events, debounce, throttle → frontend/lustre-events.md ├─ Composable UI, prop pattern, views → frontend/lustre-ui-patterns.md ├─ Hydration, server components, FFI → frontend/lustre-advanced.md ├─ Browser APIs (plinth) → frontend/lustre-browser-apis.md ├─ Testing (query, simulate, birdie) → frontend/lustre-testing.md └─ Common Lustre gotchas → frontend/lustre-gotchas.md ### "I need to design a library" Library design? ├─ Effects as data, no IO in core → library/library-design.md └─ FFI (Erlang + JavaScript) → library/ffi.md ### "I need to review OTP code" OTP review (after implementing actors/supervision)? └─ Audit actors, supervision, concurrency → Use /otp-review command **When to use /otp-review:** - After creating new actors - After modifying supervision trees - After changing actor state or message types - When experiencing timeouts, deadlocks, or memory leaks - Before committing OTP-related code Read at most 2 reference files per turn to stay token-efficient. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/aboio-labs) — claim your Tome and manage your conversions.