# Cloud Skills Recupere procedimentos reutilizáveis e versionados progressivamente e interprete runbooks operacionais estruturados entre agentes conectados. - Canonical: https://docs.xmemo.dev/pt-br/docs/concepts/cloud-skills - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: 049066d1073d736057a89262336d6fb1f3a45bde8716106959785c6f135bcab3 - Edition-Digest: 38080bb02971436049aedc1608189d98772abecd7403d8b11eb5d67434bb4a85 - Source-Revision: sha256:ed4540a74de987fd5125f372ab4ee2ea3f4d70303dedb8cef36a3395d3de069a ## Memória procedimental e arquitetura de skills As Cloud Skills fornecem memória procedimental criada pelo usuário no XMemo, permitindo que desenvolvedores e equipes salvem procedimentos operacionais padrão (SOPs), runbooks, listas de verificação e prompts reutilizáveis diretamente no armazenamento persistente. Uma vez salvos, agentes conectados em ferramentas compatíveis podem descobri-los, recuperá-los e interpretá-los sem instalação por agente ou cópia manual de prompts. Uma Cloud Skill armazenada é diferente do runtime do cliente XMemo Skill instalado (@xmemo/skill, node scripts/xmemo-skill.mjs), que serve como ponte de conexão no lado do agente. - Recurso em Preview: Cloud Skills está atualmente em Preview no Memory Console (#skills). - Identidade e ativo: Cada skill tem um skill_id exclusivo, slug legível, nome, descrição, escopo do proprietário (Personal ou Team) e status do ativo (ativo ou arquivado). - Cadeia de revisões imutável: Uma skill contém uma sequência append-only de instantâneos SkillRevision. Cada revisão possui revision_id, revision_number, instruction_body, canonical_hash e recursos tipados opcionais SkillComponent. - Limites de tamanho: Os corpos de instruções raiz são limitados a 64 KiB UTF-8. Uma revisão pode conter até 50 componentes declarados, com cada componente limitado a 128 KiB. - Tipos de recursos dos componentes: Os componentes declaram tipos semânticos explícitos incluindo reference, example, template, document, artifact e script. ## Ciclo de vida de publicação e revisão de equipe As revisões de Cloud Skill transitam por um ciclo de vida estruturado para proteger fluxos de produção e apoiar a criação colaborativa: - draft: Estado inicial de revisão durante a autoria e preparação privada antes da ativação pública. - proposed: Revisões criadas em um espaço de trabalho Team passam para o status proposed, aguardando revisão explícita e ativação por um proprietário ou administrador da equipe. - published: A revisão ativa elegível para descoberta por agentes e recuperação padrão de Nível 1. Apenas uma revisão por slug é designada como published em um determinado momento. - deprecated: Revisões mais antigas ou substituídas podem ser marcadas como deprecated para sinalizar encerramento, preservando a recuperação reproduzível histórica. - Publicação pessoal vs. equipe: Em espaços de trabalho pessoais, salvar com intenção de publicar transita diretamente para published. Em espaços de trabalho de equipe, revisões propostas (proposed) impedem que alterações procedimentais não revisadas alterem os fluxos de trabalho dos agentes. ## Recuperação progressiva: Nível 0, Nível 1, Nível 2 Agentes conectados recuperam skills sob demanda usando o Progressive Recall para evitar saturar as janelas de contexto de LLMs com documentação não utilizada: - Nível 0 (Descoberta): A pesquisa por consulta retorna descritores leves (slug, name, description) que correspondem à tarefa do usuário sem carregar instruções completas. - Nível 1 (Recuperação raiz): Recupera as instruções raiz da skill e o manifesto de componentes para um slug especificado, adotando por padrão a revisão publicada com fallback para a versão mais recente. - Nível 2 (Recuperação de recursos): Recupera um único componente declarado (como um modelo de lista de verificação ou esquema de referência), exigindo que o chamador forneça um revision_id explícito para evitar a inconsistência de recursos (resource tearing). ```text recall_cloud_skill(query="incident response") # Level 0: lightweight descriptors recall_cloud_skill(slug="incident-response-checklist") # Level 1: root instructions + manifest recall_cloud_skill( slug="incident-response-checklist", revision_id="", resource="templates/triage-template.md", ) # Level 2: one pinned resource component ``` ## A fixação de versão impede a inconsistência de recursos Quando uma skill é atualizada, o XMemo cria a próxima revisão imutável em vez de sobrescrever o conteúdo histórico. A recuperação raiz de Nível 1 entrega instruções raiz juntamente com um revision_id imutável e um manifesto de componentes. Solicitações de recursos de Nível 2 exigem que o chamador fixe esse revision_id exato. Se um autor publicar uma nova revisão enquanto um agente estiver executando um fluxo de trabalho, a leitura fixada do agente continuará resolvendo exatamente o instantâneo com o qual começou, eliminando a inconsistência de recursos. ```json { "kind": "root", "data": { "skill_id": "skill_inc_triage_01", "revision_id": "rev_v1_inc_triage", "revision_number": 1, "canonical_hash": "c7b14d8e9f2a4c10...", "resources": [ { "logical_path": "templates/triage-template.md", "type": "template", "content_hash": "e3b0c44298fc1c14..." } ] } } ``` ## Superfícies de importação, exportação e autoria Desenvolvedores podem criar Cloud Skills interativamente no console web ou importar skills existentes a partir de pacotes de distribuição padrão: - Autoria no console: Crie skills interativamente no Memory Console (#skills) com editor markdown e gerenciamento de componentes. - Importação de pacotes: Importe arquivos SKILL.md padrão (com frontmatter YAML), arquivos ZIP de múltiplos arquivos ou repositórios remotos via URL (ClawHub ou GitHub). - Diferenciação de revisões: Compare alterações de instruções e modificações de componentes entre duas revisões quaisquer com diferenciação no nível de palavras. - Exportação de Source Capsule: Exporte qualquer revisão de skill como um arquivo ZIP Source Capsule sem perdas contendo SKILL.md, recursos de componentes e manifesto de metadados. ## Perfis de acesso de agentes e isolamento em sandbox Agentes autorizados acessam Cloud Skills por meio de ferramentas MCP contratualmente definidas em ambientes de cliente suportados: - Ferramentas MCP contratadas: As ferramentas recall_cloud_skill (somente leitura) e save_cloud_skill (autoria) são contratualmente expostas nos perfis de cliente cursor-plugin e ordinary-full (config/mcp-documentation-contract.json). Elas não são expostas nos perfis generic-public, chatgpt-public ou claude-code. - Procedimentos executáveis por prompt: A maioria das Cloud Skills são procedimentos operacionais padrão interpretados diretamente por agentes como orientação de prompt sem execução de código. - Limite de execução em sandbox: A execução opcional de scripts no backend via execute_cloud_skill é um recurso avançado do lado do servidor governado pelo SandboxExecutionEngine (não exposto a nenhum perfil de cliente hoje). Quando o isolamento local de contêineres bubblewrap estiver ausente, a execução falhará em modo fechado com SANDBOX_UNAVAILABLE. ## Disponibilidade e limites do ciclo de vida Os recursos de Cloud Skill estão disponíveis se as Cloud Skills procedimentais estiverem habilitadas para sua conta. As revisões são instantâneos imutáveis endereçados por conteúdo, e salvar alterações cria uma nova revisão sem sobrescrever registros anteriores. Quando existirem skills candidatas, o console exibirá um banner de revisão exigindo promoção manual explícita. ## Usuário do ChatGPT Dê ao ChatGPT acesso duradouro às suas preferências do XMemo, fatos do projeto, decisões e TODOs sem colar tokens bearer no chat. Conecte o servidor MCP hospedado do XMemo pelo fluxo OAuth do app ChatGPT/OpenAI e aprove a concessão memory:read e memory:write para sua conta do XMemo. Salve uma preferência de teste ou anotação de projeto, inicie um novo chat e peça ao ChatGPT para recuperá-la via XMemo antes de prosseguir. Se o OAuth falhar ou as ferramentas não aparecerem, saia do servidor MCP no app host, reconecte a URL do servidor XMemo e tente novamente antes de criar tokens diretos. ## Desenvolvedor Copilot / Codex Transfira decisões do repositório, convenções de código, notas de correção de bugs e histórico de tarefas entre agentes de IDE e CLI. Use OAuth para VS Code / GitHub Copilot e Gemini CLI quando disponível. Para Copilot CLI, Codex, Cursor ou outros clientes MCP diretos, mantenha XMEMO_KEY no ambiente local ou cofre de segredos e defina um XMEMO_AGENT_INSTANCE_ID estável. Registre uma decisão da base de código ou correção de bug e peça ao próximo agente de IDE ou CLI para recuperar o contexto relevante do XMemo antes de editar. Se as recuperações estiverem vazias, verifique o caminho da configuração MCP selecionada, a variável de ambiente XMEMO_KEY para clientes diretos e eventuais credenciais OAuth desatualizadas no app host. ## Líder de piloto de equipe / corporativo Avalie a memória compartilhada com controles de conta, atribuição de origem, fluxos de exportação/exclusão e evidências de configuração seguras para revisores. Crie ou acesse o espaço de trabalho protegido do XMemo, convide usuários aprovados e conecte cada cliente via OAuth ou credencial direta com escopo de acordo com os selos de disponibilidade. Peça para um membro do piloto salvar uma memória de equipe de teste, confirme a atribuição de origem no XMemo e revise os caminhos de exclusão/exportação e suporte. Se um membro não conseguir se conectar, verifique as permissões de função, aprovação OAuth, status de prontidão do cliente e orientações de suporte antes de emitir um novo token. ## Operador de agentes autônomos Permita que agentes headless ou agendados registrem progresso, recuperem decisões anteriores e mantenham uma identidade estável e não secreta de instância. Obtenha /api/v1/mcp/config/autonomous-agent. Prefira auth_modes.oauth quando o executor suportar OAuth + cabeçalhos personalizados; use auth_modes.xmemo_key com XMEMO_KEY de um cofre de segredos apenas para executores totalmente headless. Execute uma tarefa de teste que grave progresso no XMemo, reinicie o executor e confirme se ele recupera esse progresso usando o mesmo XMEMO_AGENT_INSTANCE_ID. Se a atribuição mudar ou as recuperações se dividirem entre instâncias, persista XMEMO_AGENT_INSTANCE_ID fora do git e verifique se o executor não o está gerando a cada início.