Primeros pasos

Para agentes de IA — skill y MCP

Synsema está hecho para que lo escriban agentes. Dos cosas hacen que un agente de programación lo escriba bien, y funcionan juntas:

	Qué le da al agente	Dónde vive
El skill	La referencia completa — sintaxis, builtins, capacidades, serve, LLM, agentes, deploy, trampas — como archivos Markdown que el agente lee cuando los necesita	una carpeta en tu máquina
El MCP de las docs	Búsqueda en estas docs, cualquier página, los ejemplos doctesteados y un sandbox que ejecuta y testea Synsema, para que el agente compruebe su código antes de entregarlo	`https://synsema.dev/mcp`

Usá los dos. El skill hace que el primer borrador salga bien; el MCP atrapa lo que el borrador todavía tiene mal.

El 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

Como 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

El skill es una carpeta en el formato abierto Agent Skills: SKILL.md (la entrada) y un archivo por tema (syntax.md, builtins.md, serve.md, capabilities.md, pitfalls.md, …), todo Markdown plano, en skills/synsema/. Cada agente que lee skills lo toma solo: Claude Code desde ~/.claude/skills/, Codex desde ~/.agents/skills/, opencode desde cualquiera de los dos. En Windows, corré el instalador con curl desde Git Bash o WSL (npx anda en cualquier shell). Un agente sin skills puede leer skills/synsema/INDEX.md como contexto: apunta a todos los demás archivos.

Se instala una vez por máquina, no por proyecto. Sin -g el skill queda sólo en la carpeta actual, que es también lo que pasa cuando un agente corre el comando por vos sin -g.

Actualizalo con cada versión del motor. El skill describe una versión del lenguaje; después de synsema update, corré el mismo comando otra vez (synsema update te lo recuerda). Con una copia en más de una carpeta (Claude Code y Codex en la misma máquina), actualizalas juntas: opencode lee las dos.

El MCP de las docs§

Un servidor Model Context Protocol sobre HTTP streamable, sin clave:

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) y la mayoría de los clientes:

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

opencode (opencode.json):

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

Sus herramientas:

Herramienta	Qué hace
`search_docs`	Búsqueda por palabras en las docs (primero el índice en inglés, el español como respaldo); devuelve slug, título y descripción
`get_page`	Una página en Markdown (`slug`, por ejemplo `21-secrets`; `lang`: `en` o `es`)
`get_example`	Un ejemplo `.syn` doctesteado, por id
`run_synsema`	Ejecuta un fragmento en un sandbox: cálculo, print, secretos, SQL en memoria, archivos temporales. Sin `exec` y sin red real
`test_synsema`	Corre los bloques `test` de un fragmento en el sandbox y dice si pasan

Probalo desde una terminal:

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

Qué se manda al servidor y qué vuelve. Sólo el código Synsema que el agente quiere verificar: un fragmento, o el archivo que está escribiendo. Nunca el contenido de .env, valores de secretos, claves, tokens ni tus datos: un programa que los necesita se prueba en tu máquina. El skill le dice al agente que te pregunte antes de mandar código tuyo que sea privado. Lo que vuelve son datos (texto de las docs, un ejemplo, la salida de una corrida), que el agente lee como referencia, no como instrucciones.

El sandbox no puede salir a la red ni lanzar procesos, a propósito: el código que llama a una API o a una cadena se comprueba con synsema check y synsema test en tu máquina, donde valen tus capacidades y tu .env.

Sin MCP: llms.txt y páginas en Markdown§

https://synsema.dev/llms.txt — el índice de las docs para modelos de lenguaje (/en/llms.txt,

/es/llms.txt por idioma).

Cada página está también en Markdown: agregá .md a su URL, por ejemplo

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

El ciclo que funciona§

1. El agente lee el skill y escribe el programa, primero las líneas require. 2. Comprueba partes con test_synsema / run_synsema a través del MCP. 3. En tu máquina: synsema check app.syn (parseo, imports, plantillas — y un aviso por cada nombre de builtin deprecado o construcción cuyo significado cambió, así un borrador escrito desde un recuerdo viejo del lenguaje se corrige) y synsema test app.syn. 4. synsema serve app.syn o synsema run app.syn para verlo funcionar. 5. Desplegalo: en tu propio servidor (Deploy), o con syn deploy en la plataforma (Plataforma Synsema).