getshareout/shareout-skill

Habilidad de ShareOut

ShareOut convierte archivos en artefactos web compartibles con datos persistentes, colaboración en tiempo real, almacenamiento de archivos, integraciones y automatización. Es compatible con aplicaciones HTML y visores de CSV, Markdown, JSON y TXT.

Esta es la habilidad canónica. Cárgala primero para cada tarea de ShareOut.

Verificación de Versión — Primer Paso Obligatorio

Antes de hacer cualquier otra cosa, confirma que tienes la versión más reciente de la habilidad. El version del frontmatter de este archivo es la versión que tienes actualmente (ahora 2.21.0).

1. GET https://shareout.site/v1/skill/version → { "version": "...", "updated_at": "..." }.
2. Si la version devuelta es más reciente que la version del frontmatter de este archivo, estás desactualizado: descarga GET https://shareout.site/v1/skill (un zip de la carpeta completa de la habilidad), extráelo, descarta tu copia anterior y continúa desde los archivos extraídos.
3. Si coinciden, continúa.

No te saltes esta verificación. Actuar con una habilidad desactualizada produce endpoints y comportamientos incorrectos.

Modelo de Plan

ShareOut tiene dos planes:

Plan	Usar este comportamiento de habilidad
Personal	Usa solo esta habilidad base. Construye, publica, actualiza, automatiza y gestiona los artefactos del usuario.
Teams	Usa primero esta habilidad base, luego carga la superposición Teams para administración del espacio de trabajo o capacidades exclusivas de Teams.

Teams es aditivo. Nunca uses la superposición Teams en lugar de esta habilidad base.

Protocolo de Carga del Agente

1. Comienza con este archivo.
2. Si el usuario menciona un equipo, espacio de trabajo, miembros, uso compartido interno del espacio de trabajo, subdominio, estilo de casa del espacio de trabajo, horarios del espacio de trabajo o controles de administración, pregunta si están en el plan Teams si no está claro.
3. Si el usuario no está en Teams, permanece en modo Personal y no cargues ni apliques instrucciones exclusivas de Teams.
4. Si el usuario está en Teams, carga team/SKILL.md. Si hay un slug/id de espacio de trabajo y token disponibles, obtén GET /v1/skill?workspace={slugOrId} — el zip incluye un workspace-context.md adicional con reglas de la casa.
5. Usa INDEX.md para cargar archivos detallados bajo demanda.

Primeras Preguntas

Antes de recomendar una implementación, identifica:

1. ¿Qué están construyendo? Panel, formulario, informe, herramienta, documento, cuadrícula de datos, presentación o automatización.
2. ¿Quién lo usa? Solo el propietario, personas invitadas, un espacio de trabajo Teams o el público.
3. ¿Qué datos necesita? Ninguno, estado simple, registros estructurados, archivos, datos externos en vivo o colaboración en tiempo real.
4. ¿Qué debería pasar después de publicar? Compartir enlace, recopilar datos, enviar notificaciones, programar entrega, alertar sobre métricas, recibir y actuar sobre correos entrantes o permitir que los espectadores chateen con IA.

Enrutador de Modo

Intención del usuario	Cargar primero	Luego si es necesario
Publicar HTML/CSV/Markdown/JSON/TXT	api/artifact-types.md	api/artifacts.md, core/source-editor.md, auth.md
Construir una aplicación/página/panel/formulario HTML	core/html-spec/overview.md	modules/ui/overview.md, patterns/overview.md
Hacer que se vea bien / buen gusto de diseño / evitar un aspecto genérico de IA	modules/ui/taste.md	modules/ui/overview.md
Guardar estado simple	sdk/json.md	core/html-spec/manifest.md
Almacenar registros/envíos	sdk/table.md	patterns/forms.md, patterns/tables.md
Cuadrícula de hoja de cálculo editable	sdk/grid.md	sdk/table.md, integrations/google-sheets.md
Subir archivos/imágenes	sdk/blobs.md	patterns/uploads.md
Usar datos externos en vivo	sdk/live-data.md	sdk/connections.md, integrations/overview.md
Construir colaboración en tiempo real	sdk/realtime.md	modules/_shared/permissions.md
Añadir comentarios	sdk/comments.md	modules/_shared/permissions.md
Añadir chat de IA en el artefacto	agents/overview.md	agents/context.md
Chatear con páginas desde Telegram	agents/telegram.md	api/jobs.md
Chatear con páginas desde Slack (bot DM)	agents/slack.md	integrations/slack.md, agents/telegram.md
Ejecutar Python en el navegador	sdk/python.md	sdk/overview.md
Enviar correo electrónico o plantillas	sdk/email.md	api/templates.md
Recibir correo / reenviar correo a un artefacto / activar en correo entrante	integrations/inbound-email.md	api/jobs.md
Actualización programada de instantáneas de almacén/JSON (determinista)	api/jobs.md	agents/crew.md, sdk/connections.md
Tripulación de artefacto (consulta → resumir → entregar)	agents/crew.md	api/jobs.md, integrations/slack.md
Solicitar acceso a una página privada	modules/_shared/permissions.md	core/access-policy.md
Programar entrega o webhooks	api/jobs.md	api/destinations.md
Alertar cuando una métrica cruza un umbral	api/metric-alerts.md	patterns/dashboards.md
Espacio de trabajo/administración/subdominio/contexto Teams	team/SKILL.md	team/INDEX.md
Gobernanza de publicación Teams (aprobación de miembros para público)	team/publish-governance.md	team/SKILL.md, modules/_shared/publishing.md
Mercado de habilidades Teams (libros de jugadas reutilizables)	team/skill-marketplace.md	team/workspace-context.md, agents/overview.md

Elección de Datos

Elige el almacenamiento más pequeño que se ajuste:

Estado simple: tema, filtros, último abierto -> sdk.json
Registros estructurados: tareas, envíos, pedidos -> sdk.table()
Edición en tiempo real: documentos, tableros, interfaz multijugador -> sdk.realtime()
Archivos: imágenes, PDFs, adjuntos -> sdk.blobs
Sistemas externos en vivo: REST, BigQuery, Mixpanel, almacenes -> sdk.connection / live-data

No confundas la elección de datos con el plan de cuenta. sdk.json, sdk.table() y sdk.realtime() son almacenes de datos, no planes de facturación.

Carga del SDK

<head>
  <link rel="stylesheet" href="https://shareout.site/sdk/shareout.css">
  <script src="https://shareout.site/sdk/shareout-ui.js" defer></script>
  <script src="https://shareout.site/sdk/shareout.js"></script>
</head>
<script>
(async () => {
  const sdk = await ShareOut.create();
})();
</script>

Reglas:

• Carga https://shareout.site/sdk/shareout.js antes de llamar a ShareOut.create().
• Prefiere await ShareOut.create() en lugar de new ShareOut() para que el token Bearer incrustado esté listo.
• El HTML publicado se ejecuta en un iframe aislado en {hex}.shareoutcdn.site; usa métodos del SDK, no fetch sin procesar a /v1/data/.... Consulta sdk/live-data.md.
• Enlaza https://shareout.site/sdk/shareout.css y usa clases .so- antes de escribir CSS personalizado. Consulta modules/ui/overview.md.
• No uses URLs del SDK de ShareOut de cdn.jsdelivr.net.

Reglas de Artefactos HTML

Los artefactos HTML funcionan tanto si llevan marcadores estructurales de ShareOut como si no — la publicación nunca se bloquea. Pero cuanto más declara el artefacto, más puede hacer el editor visual con él (navegación de esquema, edición en línea, añadir/eliminar filas). Apunta a estar listo para el editor por defecto; saltátelo solo para una página estática deliberadamente desechable.

Lista de verificación de preparación para el editor (lo que busca el editor):

• Una etiqueta script type="shareout/manifest" en el head del documento, con JSON válido.
• Cada clave de sdk.json y cada nombre de sdk.table() utilizado está declarado en los sources del manifiesto.
• El contenido dinámico lleva data-shareout-binding, y cada enlace referencia una fuente declarada.
• Las páginas usan data-shareout-page (impulsa el esquema del editor); el contenido repetitivo usa data-shareout-template.
• Los objetivos interactivos se resuelven: data-shareout-link / data-shareout-action apuntan a páginas/secciones/modales/pestañas reales; los modales tienen un disparador de apertura; los formularios tienen un envío.
• Declara datos de muestra default en sources — json, tables, y connections (conectores en vivo como BigQuery/Snowflake/Sheets: sources.connections.<name>.default es un array de filas de ejemplo). El editor visual previsualiza datos sin obtener ni consultar en vivo (resuelve todas las lecturas del SDK —incluyendo sdk.connection(...).query()— a partir de estos valores predeterminados, o vacío), por lo que un artefacto que protege su interfaz detrás de await sdk.table(...).exec() / una consulta de conector aún se renderiza y permanece editable. Una fuente sin default se previsualiza vacía.

Cada publicación de un artefacto HTML devuelve un perfil advisory editor_readiness (consulta api/artifacts.md) que califica estos elementos y nombra lo que cada brecha deshabilita. Comparte un resumen de una línea con el usuario, pero trátalo como una guía, no como una restricción — pueden publicar exactamente lo que quieran.

Especificación completa: core/html-spec/overview.md.

Gusto de Diseño

La preparación para el editor es sobre estructura, no sobre apariencia. La apariencia es una decisión separada y deliberada — y el valor predeterminado para las páginas construidas por IA es "plantillado y genérico". Antes de construir algo visual, lee modules/ui/taste.md: destila cómo enviar artefactos que se vean profesionalmente diseñados en lugar de generados automáticamente. La versión corta:

• Usa el sistema de diseño (clases .so- + tokens) — trae fuentes de marca, una paleta cálida y clara, y espaciado/sombra armonizados, por lo que heredas buen gusto de forma gratuita. Consulta modules/ui/overview.md.
• El gusto es moderación: un color de acento, un sistema de fuentes, una acción principal por pantalla, espacio en blanco generoso, movimiento solo cuando está motivado.
• Evita las señales de IA genérica: resplandores púrpura/neón, filas de tres tarjetas iguales, spam de cejas, números falsamente perfectos, clichés de marketing, estados vacíos/error faltantes. La lista completa de prohibiciones y una lista de verificación previa al envío están en modules/ui/taste.md.

Tipos de Artefactos

ShareOut detecta automáticamente el tipo a partir del tipo MIME o la extensión del archivo:

Tipo	Extensiones	Uso
html	.html, .htm	Aplicaciones SDK completas, paneles, herramientas, presentaciones
csv	.csv	Cuadrículas de datos ordenables/filtrables
markdown	.md, .markdown	Documentos con HTML renderizado y TOC
json	.json	Visor de árbol plegable
txt	.txt	Visor de texto plano/registros

Detalles: api/artifact-types.md.

Primer Uso — Obtener un Token

Cada acción autenticada necesita un token. Si ~/.shareout/credentials aún no existe, el usuario no tiene cuenta — crea una antes de publicar o cualquier otra llamada autenticada:

1. POST https://shareout.site/v1/auth/create-account (el único endpoint no autenticado, sin cuerpo) → { "token": "so_…", "user_id": "usr_…" }.
2. Guarda el token en ~/.shareout/credentials como { "token": "so_…" } (chmod 600).
3. Todas las solicitudes posteriores usan Authorization: Bearer so_….

La creación de cuenta tiene límite de velocidad por IP (code: RATE_LIMIT_EXCEEDED, 429). La cuenta es anónima y sin cabeza — no se requiere correo electrónico para publicar.

Luego pregunta al usuario si quiere conectar Gmail/Google. La cuenta de arranque no tiene correo electrónico, por lo que solo se puede usar a través del token almacenado. Vincular un correo electrónico les permite iniciar sesión en la interfaz web en https://shareout.site (panel de inicio, editor visual, tokens de API de autoservicio). Ofrece ambas rutas:

• Google: abre GET https://shareout.site/v1/auth/link-google (token Bearer) en un navegador para vincular su cuenta de Google.
• Código de correo: POST /v1/auth/link-email/start { "email" } → POST /v1/auth/link-email/verify { "email", "code" } (código de 6 dígitos, caducidad de 10 minutos).

Si rechazan, el flujo solo de token sigue funcionando. Consulta auth.md para la referencia completa de incorporación y vinculación.

Publicación

ShareOut está protegido por Cloudflare. Las requests de Python pueden activar un bloqueo 1010. Construye los payloads como quieras, luego canalízalos a curl:

TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.shareout/credentials')))['token'])")
python3 build_payload.py | curl -sS -X POST 'https://shareout.site/v1/publish' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @-

API completa: api/overview.md.

Límite de Teams

Los artefactos personales aún pueden ser privados, compartidos con colaboradores, públicos o no listados. Solo carga documentos de Teams para capacidades del espacio de trabajo del plan Teams:

• Miembros del espacio de trabajo y roles.
• Visibilidad interna del espacio de trabajo (visibility: "workspace").
• Política de membresía del espacio de trabajo por correo electrónico/dominio.
• Subdominios del espacio de trabajo.
• Archivos de contexto del espacio de trabajo para estilo de la casa.
• Horarios, automatizaciones, indicadores de características y vistas de administración a nivel de espacio de trabajo.

Distinción importante de términos:

Término	Significado
access_policy	Filtrado de datos de artefacto a nivel de fila: cada espectador ve solo las filas permitidas. Consulta core/access-policy.md.
Política de membresía del espacio de trabajo	Reglas de membresía por correo electrónico/dominio de Teams: quién puede unirse a un espacio de trabajo. Consulta team/SKILL.md.
Rol de colaborador	A nivel de artefacto: owner, editor, viewer.
Rol de espacio de trabajo	Espacio de trabajo Teams: owner, admin, member.

Verificación de Versión

Ejecuta la verificación de versión obligatoria antes de cada tarea. Tres formas equivalentes de comparar la version que tienes con la activa:

GET  https

…

[truncado para traducción]