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§

curl -sL https://raw.githubusercontent.com/kitecosmic/synsema/main/install-skill.sh | bash

Escribe el skill en ~/.claude/skills/synsema/ — SKILL.md (la entrada) y un archivo por tema (syntax.md, builtins.md, serve.md, capabilities.md, pitfalls.md, …). Claude Code lo detecta solo. En Windows, correlo desde Git Bash o WSL.

Otros agentes (Cursor, Windsurf, Codex, …) leen los mismos archivos: apuntá las reglas o el contexto de tu agente a esa carpeta, o copiala donde tu agente busca instrucciones. Son Markdown plano.

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).

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

Cursor (.cursor/mcp.json) y la mayoría de los clientes:

{
  "mcpServers": {
    "synsema-docs": { "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"}'

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 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).