getshareout/shareout-skill

Skill ShareOut

O ShareOut transforma arquivos em artefatos web compartilháveis com dados persistentes, colaboração em tempo real, armazenamento de arquivos, integrações e automação. Ele suporta aplicativos HTML além de visualizadores para CSV, Markdown, JSON e TXT.

Este é o skill canônico. Carregue-o primeiro para cada tarefa do ShareOut.

Verificação de Versão — Primeiro Passo Obrigatório

Antes de fazer qualquer outra coisa, confirme que você tem o skill mais recente. O version no frontmatter deste arquivo é a versão que você possui atualmente (agora 2.21.0).

1. GET https://shareout.site/v1/skill/version → { "version": "...", "updated_at": "..." }.
2. Se o version retornado for mais novo que o version do frontmatter deste arquivo, você está desatualizado: baixe GET https://shareout.site/v1/skill (um zip da pasta completa do skill), extraia-o, descarte sua cópia antiga e continue a partir dos arquivos extraídos.
3. Se coincidirem, prossiga.

Não pule esta verificação. Agir com um skill desatualizado resulta em endpoints e comportamento errados.

Modelo de Plano

O ShareOut tem dois planos:

Plano	Use este comportamento do skill
Personal	Use apenas este skill base. Construa, publique, atualize, automatize e gerencie os próprios artefatos do usuário.
Teams	Use este skill base primeiro, depois carregue a sobreposição Teams para administração de workspace ou capacidades exclusivas do Teams.

Teams é aditivo. Nunca use a sobreposição Teams em vez deste skill base.

Protocolo de Carregamento do Agente

1. Comece com este arquivo.
2. Se o usuário mencionar uma equipe, workspace, membros, compartilhamento interno no workspace, subdomínio, estilo de casa do workspace, agendamentos do workspace ou controles de administrador, pergunte se ele está no plano Teams, se ainda não estiver claro.
3. Se o usuário não estiver no Teams, permaneça no modo Personal e não carregue nem aplique instruções exclusivas do Teams.
4. Se o usuário estiver no Teams, carregue team/SKILL.md. Se um slug/id e token do workspace estiverem disponíveis, busque GET /v1/skill?workspace={slugOrId} — o zip inclui um workspace-context.md extra com regras da casa.
5. Use INDEX.md para carregar arquivos detalhados sob demanda.

Primeiras Perguntas

Antes de recomendar uma implementação, identifique:

1. O que estão construindo? Dashboard, formulário, relatório, ferramenta, documento, grade de dados, apresentação ou automação.
2. Quem usa? Apenas o proprietário, pessoas convidadas, um workspace Teams ou o público.
3. Quais dados precisa? Nenhum, estado simples, registros estruturados, arquivos, dados externos ao vivo ou colaboração em tempo real.
4. O que deve acontecer após a publicação? Compartilhar link, coletar dados, enviar notificações, agendar entrega, alertar sobre métricas, receber e agir sobre e-mails de entrada, ou permitir que visualizadores conversem com IA.

Roteador de Modo

Intenção do usuário	Carregue primeiro	Depois, se necessário
Publicar HTML/CSV/Markdown/JSON/TXT	api/artifact-types.md	api/artifacts.md, core/source-editor.md, auth.md
Construir uma página/aplicativo/dashboard/formulário HTML	core/html-spec/overview.md	modules/ui/overview.md, patterns/overview.md
Deixá-lo com boa aparência / bom gosto de design / evitar aparência genérica de IA	modules/ui/taste.md	modules/ui/overview.md
Salvar estado simples	sdk/json.md	core/html-spec/manifest.md
Armazenar registros/envios	sdk/table.md	patterns/forms.md, patterns/tables.md
Grade de planilha editável	sdk/grid.md	sdk/table.md, integrations/google-sheets.md
Enviar arquivos/imagens	sdk/blobs.md	patterns/uploads.md
Usar dados externos ao vivo	sdk/live-data.md	sdk/connections.md, integrations/overview.md
Construir colaboração em tempo real	sdk/realtime.md	modules/_shared/permissions.md
Adicionar comentários	sdk/comments.md	modules/_shared/permissions.md
Adicionar chat de IA no artefato	agents/overview.md	agents/context.md
Conversar com páginas do Telegram	agents/telegram.md	api/jobs.md
Conversar com páginas do Slack (bot DM)	agents/slack.md	integrations/slack.md, agents/telegram.md
Executar Python no navegador	sdk/python.md	sdk/overview.md
Enviar e-mail ou modelos	sdk/email.md	api/templates.md
Receber e-mail / encaminhar e-mail para um artefato / acionar com e-mail de entrada	integrations/inbound-email.md	api/jobs.md
Atualização programada de snapshot warehouse/json (determinística)	api/jobs.md	agents/crew.md, sdk/connections.md
Equipe de artefato (consultar → resumir → entregar)	agents/crew.md	api/jobs.md, integrations/slack.md
Solicitar acesso a uma página privada	modules/_shared/permissions.md	core/access-policy.md
Agendar entrega ou webhooks	api/jobs.md	api/destinations.md
Alertar quando uma métrica ultrapassar um limite	api/metric-alerts.md	patterns/dashboards.md
Workspace/admin/subdomínio/contexto Teams	team/SKILL.md	team/INDEX.md
Governança de publicação Teams (aprovação de membro para público)	team/publish-governance.md	team/SKILL.md, modules/_shared/publishing.md
Mercado de skills Teams (playbooks reutilizáveis)	team/skill-marketplace.md	team/workspace-context.md, agents/overview.md

Escolha de Dados

Escolha o menor armazenamento que atenda:

Estado simples: tema, filtros, último aberto -> sdk.json
Registros estruturados: tarefas, envios, pedidos -> sdk.table()
Edição em tempo real: documentos, quadros, UI multijogador -> sdk.realtime()
Arquivos: imagens, PDFs, anexos -> sdk.blobs
Sistemas externos ao vivo: REST, BigQuery, Mixpanel, warehouses -> sdk.connection / live-data

Não confunda escolha de dados com plano de conta. sdk.json, sdk.table() e sdk.realtime() são armazenamentos de dados, não planos de faturamento.

Carregamento do 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>

Regras:

• Carregue https://shareout.site/sdk/shareout.js antes de chamar ShareOut.create().
• Prefira await ShareOut.create() em vez de new ShareOut() para que o token Bearer incorporado esteja pronto.
• O HTML publicado é executado em um iframe com sandbox em {hex}.shareoutcdn.site; use métodos do SDK, não fetch bruto para /v1/data/.... Veja sdk/live-data.md.
• Vincule https://shareout.site/sdk/shareout.css e use classes .so- antes de escrever CSS personalizado. Veja modules/ui/overview.md.
• Não use URLs do SDK ShareOut de cdn.jsdelivr.net.

Regras de Artefato HTML

Artefatos HTML funcionam independentemente de terem ou não os marcadores estruturais do ShareOut — a publicação nunca é bloqueada. Mas quanto mais o artefato declarar, mais o editor visual pode fazer com ele (navegação por contorno, edição inline, adicionar/remover linhas). Mire em pronto-para-editor por padrão; pule apenas para uma página estática deliberadamente descartável.

Lista de verificação de prontidão para o editor (o que o editor procura):

• Uma tag script type="shareout/manifest" no head do documento, com JSON válido.
• Toda chave sdk.json e nome sdk.table() usado é declarado nos sources do manifesto.
• Conteúdo dinâmico carrega data-shareout-binding, e cada binding referencia uma fonte declarada.
• Páginas usam data-shareout-page (controla o contorno do editor); conteúdo repetido usa data-shareout-template.
• Alvos interativos resolvem: data-shareout-link / data-shareout-action apontam para páginas/seções/modais/abas reais; modais têm um gatilho de abertura; formulários têm um envio.
• Declare dados de amostra default nos sources — json, tables e connections (conectores ao vivo como BigQuery/Snowflake/Sheets: sources.connections.<name>.default é um array de linhas de amostra). O editor visual pré-visualiza dados sem busca ou consulta ao vivo (ele resolve todas as leituras do SDK — incluindo sdk.connection(...).query() — a partir desses padrões, ou vazio), então um artefato que bloqueia sua UI atrás de await sdk.table(...).exec() / uma consulta de conector ainda renderiza e permanece editável. Uma fonte sem default pré-visualiza vazio.

Toda publicação de um artefato HTML retorna um perfil advisory editor_readiness (veja api/artifacts.md) que classifica esses pontos e nomeia o que cada lacuna desabilita. Compartilhe um resumo de uma linha com o usuário, mas trate como orientação, não como bloqueio — eles podem publicar exatamente o que quiserem.

Especificação completa: core/html-spec/overview.md.

Bom Gosto de Design

Prontidão para o editor é sobre estrutura, não aparência. Aparência é uma decisão separada e deliberada — e o padrão para páginas construídas por IA é "modelado e genérico." Antes de construir qualquer coisa visual, leia modules/ui/taste.md: ele destila como entregar artefatos que parecem projetados profissionalmente em vez de gerados automaticamente. A versão resumida:

• Use o sistema de design (classes .so- + tokens) — ele fornece fontes da marca, uma paleta clara e quente e espaçamento/sombra harmonizados, então você herda bom gosto de graça. Veja modules/ui/overview.md.
• Bom gosto é moderação: uma cor de destaque, um sistema de fonte, uma ação primária por tela, espaçamento generoso, movimento apenas quando motivado.
• Evite os sinais de AI-slop: brilhos roxos/neon, linhas de três cartões iguais, spam de sobrancelhas, números falsamente perfeitos, clichês de marketing, estados vazios/de erro ausentes. A lista completa de proibições e uma lista de verificação pré-publicação estão em modules/ui/taste.md.

Tipos de Artefato

O ShareOut detecta automaticamente o tipo pelo tipo MIME ou extensão do arquivo:

Tipo	Extensões	Uso
html	.html, .htm	Aplicativos SDK completos, dashboards, ferramentas, apresentações
csv	.csv	Grades de dados ordenáveis/filtráveis
markdown	.md, .markdown	Documentos com HTML renderizado e TOC
json	.json	Visualizador de árvore colapsável
txt	.txt	Visualizador de texto simples/log

Detalhes: api/artifact-types.md.

Primeira Execução — Obter um Token

Toda ação autenticada precisa de um token. Se ~/.shareout/credentials ainda não existir, o usuário não tem conta — crie uma antes de publicar ou qualquer outra chamada autenticada:

1. POST https://shareout.site/v1/auth/create-account (o único endpoint não autenticado, sem corpo) → { "token": "so_…", "user_id": "usr_…" }.
2. Salve o token em ~/.shareout/credentials como { "token": "so_…" } (chmod 600).
3. Todas as requisições posteriores usam Authorization: Bearer so_….

A criação de conta é limitada por IP (code: RATE_LIMIT_EXCEEDED, 429). A conta é anônima e sem cabeça — nenhum email necessário para publicar.

Então pergunte ao usuário se ele quer conectar o Gmail/Google. A conta bootstrap não tem email, então só pode ser usada através do token armazenado. Vincular um email permite que eles façam login na interface web em https://shareout.site (dashboard inicial, editor visual, tokens de API self-serve). Ofereça ambos os caminhos:

• Google: abra GET https://shareout.site/v1/auth/link-google (token Bearer) em um navegador para vincular sua conta Google.
• Código de email: POST /v1/auth/link-email/start { "email" } → POST /v1/auth/link-email/verify { "email", "code" } (código de 6 dígitos, expira em 10 min).

Se eles recusarem, o fluxo somente token continua funcionando. Veja auth.md para a referência completa de onboarding e vinculação.

Publicação

O ShareOut é protegido pelo Cloudflare. Python requests pode acionar um bloqueio 1010. Construa os payloads como quiser, depois envie para 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.

Limite do Teams

Artefatos Personal ainda podem ser privados, compartilhados com colaboradores, públicos ou não listados. Carregue documentos do Teams apenas para capacidades de workspace do plano Teams:

• Membros e funções do workspace.
• Visibilidade interna do workspace (visibility: "workspace").
• Política de associação ao workspace por email/domínio.
• Subdomínios do workspace.
• Arquivos de contexto do workspace para estilo da casa.
• Agendamentos, automações, feature flags e visualizações de administrador em nível de workspace.

Distinção importante de termos:

Termo	Significado
access_policy	Filtragem de dados de artefato em nível de linha: cada visualizador vê apenas as linhas permitidas. Veja core/access-policy.md.
Política de associação ao workspace	Regras de associação por email/domínio do Teams: quem pode entrar em um workspace. Veja team/SKILL.md.
Função de colaborador	owner, editor, viewer em nível de artefato.
Função no workspace	owner, admin, member do workspace Teams.

Verificação de Versão

Execute a verificação de versão obrigatória antes de cada tarefa. Três formas equivalentes de comparar sua version mantida com a versão ao vivo:

GET  https

…

[truncado para tradução]