Getting Started

For AI agents — skill and MCP

Synsema is written to be written by agents. Two things make a coding agent good at it, and they work together:

	What it gives the agent	Where it lives
The skill	The whole reference — syntax, builtins, capabilities, serve, LLM, agents, deploy, pitfalls — as Markdown files the agent reads when it needs them	a folder on your machine
The docs MCP	Search over these docs, any page, the doctested examples, and a sandbox that runs and tests Synsema so the agent checks its code before handing it over	`https://synsema.dev/mcp`

Use both. The skill makes the first draft right; the MCP catches what the draft still gets wrong.

The skill§

# Any agent: Claude Code, Codex, opencode, Cursor, Gemini CLI, GitHub Copilot, Windsurf, …
npx skills add kitecosmic/synsema -g -y       # once per machine: every project, every agent it detects
npx skills add kitecosmic/synsema -g -a codex  # one agent only
npx skills update -g                           # after `synsema update`

# Without Node
curl -fsSL https://raw.githubusercontent.com/kitecosmic/synsema/main/install-skill.sh | bash                    # ~/.claude/skills (Claude Code)
curl -fsSL https://raw.githubusercontent.com/kitecosmic/synsema/main/install-skill.sh | bash -s -- --agents      # ~/.agents/skills (Codex, opencode, …)
curl -fsSL https://raw.githubusercontent.com/kitecosmic/synsema/main/install-skill.sh | bash -s -- --dir <folder> # any other skills folder

As a plugin:

/plugin marketplace add kitecosmic/synsema     # Claude Code, then: /plugin install synsema@synsema
codex plugin marketplace add kitecosmic/synsema && codex plugin add synsema@synsema   # Codex

The skill is one folder in the open Agent Skills format: SKILL.md (the entry point) and one file per topic (syntax.md, builtins.md, serve.md, capabilities.md, pitfalls.md, …), all plain Markdown, in skills/synsema/. Every agent that reads skills picks it up by itself: Claude Code from ~/.claude/skills/, Codex from ~/.agents/skills/, opencode from either. On Windows, run the curl installer from Git Bash or WSL (npx works in any shell). An agent without skills can read skills/synsema/INDEX.md as context: it points to every other file.

Install it once per machine, not per project. Without -g the skill goes into the current folder only — which is also what happens when an agent runs the command for you without -g.

Refresh it on every engine release. The skill describes one version of the language; after synsema update, run the same command again (synsema update reminds you). With a copy in more than one folder (Claude Code and Codex on the same machine), update them together: opencode reads both.

The docs MCP§

A Model Context Protocol server over streamable HTTP, no key needed:

claude mcp add --transport http synsema-docs https://synsema.dev/mcp     # Claude Code
codex mcp add synsema-docs --url https://synsema.dev/mcp                  # Codex
gemini mcp add --transport http synsema-docs https://synsema.dev/mcp     # Gemini CLI

Cursor (.cursor/mcp.json) and most other clients:

{
  "mcpServers": {
    "synsema-docs": { "url": "https://synsema.dev/mcp" }
  }
}

opencode (opencode.json):

{
  "mcp": {
    "synsema-docs": { "type": "remote", "url": "https://synsema.dev/mcp" }
  }
}

Its tools:

Tool	What it does
`search_docs`	Keyword search over the docs (English index first, Spanish as fallback); returns slug, title and description
`get_page`	One page as Markdown (`slug`, e.g. `21-secrets`; `lang`: `en` or `es`)
`get_example`	A doctested `.syn` example by id
`run_synsema`	Runs a snippet in a sandbox: compute, print, secrets, in-memory SQL, scratch files. No `exec` and no real network
`test_synsema`	Runs a snippet's `test` blocks in the sandbox and reports pass/fail

Check it from a terminal:

curl -s -X POST https://synsema.dev/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

What goes to the server, and what comes back. Only the Synsema code the agent wants checked — a snippet, or the file it is writing. Never the contents of .env, secret values, keys, tokens or your data: a program that needs them is tested on your machine. The skill tells the agent to ask you before sending code of yours that is private. What comes back is data (docs text, an example, the output of a run), which the agent reads as reference, not as instructions.

The sandbox cannot reach the network or run processes, on purpose: code that calls an API or a chain is checked with synsema check and synsema test on your machine, where your capabilities and your .env apply.

Without MCP: llms.txt and Markdown pages§

https://synsema.dev/llms.txt — the index of the docs for language models (/en/llms.txt,

/es/llms.txt per language).

Every page is also Markdown: add .md to its URL, e.g.

https://synsema.dev/en/0.6.x/21-secrets.md.

The loop that works§

1. The agent reads the skill and writes the program, require lines first. 2. It checks pieces with test_synsema / run_synsema through the MCP. 3. On your machine: synsema check app.syn (parse, imports, templates — and a warning for every deprecated builtin name or construct whose meaning changed, so a draft written from an older memory of the language gets corrected) and synsema test app.syn. 4. synsema serve app.syn or synsema run app.syn to see it work. 5. Deploy it: your own server (Deploy), or syn deploy to the hosted platform (Synsema platform).