# Guia de Cloud Skills Crie, revise, publique e recupere progressivamente habilidades procedimentais reutilizáveis em todos os agentes conectados. - Canonical: https://docs.xmemo.dev/pt-br/docs/guides/cloud-skills - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: bff532eedc870bca9f5f7c7413891d20ab5e233fb9fdcccd4e6d38b38aba2d9e - Edition-Digest: cab53013fa7dfb81d40385e26531a62019f5e4b043fce6f455c79f4559ff66df - Source-Revision: sha256:2ed8d0fb7f3432c8695de21a099b7ce6fd715f59effbe3a2bb60822a68e1af34 ## Objetivo do usuário Crie, revise, publique e recupere habilidades procedimentais reutilizáveis (como runbooks, listas de verificação e procedimentos operacionais padrão) em todos os agentes conectados sem copiar e colar manualmente, configuração repetida por agente ou sobrecarga da janela de contexto. ## Disponibilidade e pré-requisitos Cloud Skills está atualmente em Preview na Memory Console em https://xmemo.dev/me#skills. Certifique-se de que seu ambiente atenda aos seguintes requisitos antes de criar ou recuperar skills: - Habilitação de recurso: ativo quando procedural Cloud Skills estiver habilitado para sua conta. - Seleção de espaço de trabalho: o espaço pessoal (https://xmemo.dev/me#skills) armazena skills privadas. O espaço de equipe (https://xmemo.dev/me?space=#skills) compartilha skills entre membros autenticados da equipe com governança baseada em papéis. - Escopos de token do agente: a recuperação do agente requer o escopo skills:read ou memory:read. A criação de skills e a publicação de revisões exigem o escopo skills:write ou memory:write. - Perfis de cliente suportados: as ferramentas MCP recall_cloud_skill e save_cloud_skill estão expostas nos perfis de cliente cursor-plugin e ordinary-full; interfaces públicas e de chat genéricas não expõem ferramentas de criação de skills diretamente. ## 1. Navegar até Cloud Skills na Memory Console Abra a Memory Console e selecione a seção Cloud Skills: - Espaço pessoal: abra https://xmemo.dev/me#skills para gerenciar seus runbooks procedimentais pessoais. - Espaço de equipe: abra https://xmemo.dev/me?space=#skills para gerenciar skills organizacionais compartilhadas. - Interface do console: o painel exibe a lista de skills, barra de pesquisa ("Search skills by name, slug, or keywords...") e ações principais: "New Skill" e "Import Skill". ## 2. Criar uma skill procedimental e componentes declarados Clique em "New Skill" para abrir o modal de criação de skill. Configure os metadados da skill, instruções raiz e recursos de componentes: - Skill Name: insira "Incident Response Checklist" (campo obrigatório). - Slug: insira um identificador em letras minúsculas "incident-response-checklist" (1–64 caracteres alfanuméricos ou hifens). - Description: insira "Standard operating procedure for triaging and resolving high-severity production incidents.". - Instructions: escreva orientações procedimentais raiz em markdown (limitado a 64 KiB UTF-8). - Components: adicione o componente de modelo templates/triage-template.md com o tipo template contendo o questionário de incidentes. ```markdown # Incident Response Checklist When a high-severity production alert triggers: 1. Identify the impacted service and declare an incident channel. 2. Verify service error rates and recent deployment events. 3. Complete the triage questionnaire at `templates/triage-template.md`. 4. Apply documented mitigation or initiate canary rollback. 5. Record timeline events and assign follow-up action items. ``` ## 3. Revisar e publicar a revisão da skill Salve a revisão da skill e observe como a publicação se comporta entre os espaços pessoal e de equipe: - Publicação pessoal: em um espaço de trabalho pessoal, salvar com intenção de publicação faz a transição da revisão v1 diretamente para "Published", tornando-a imediatamente localizável para agentes autorizados. - Fluxo de revisão em equipe: em um espaço de trabalho de equipe, salvar cria a revisão v1 com o status "proposed". Os membros da equipe podem revisar as instruções, inspecionar diferenças de componentes e testar a execução antes que um proprietário ou administrador da equipe publique a revisão. - Fase de rascunho: se a intenção de publicação estiver desmarcada, a revisão permanecerá no status "Draft" para edição e testes privados sem expô-la à descoberta de agentes. ## 4. Verificar a recuperação progressiva do agente Agentes conectados consultam e recuperam skills publicadas sob demanda em três níveis progressivos para preservar os limites de contexto: - Nível 0 (Descoberta): o agente pesquisa por consulta de tarefa e recebe descritores leves sem as instruções completas. - Nível 1 (Instruções raiz): o agente recupera as instruções raiz e o manifesto de componentes usando o slug da skill. - Nível 2 (Recurso fixado): o agente recupera o componente de modelo declarado fornecendo o revision_id exato retornado no Nível 1. ```text # Level 0: Discover relevant skills by task query recall_cloud_skill(query="incident response") # Level 1: Retrieve root instructions and component manifest recall_cloud_skill(slug="incident-response-checklist") # Level 2: Retrieve pinned component resource without resource tearing recall_cloud_skill( slug="incident-response-checklist", revision_id="", resource="templates/triage-template.md", ) ``` ## 5. Atualizar procedimento e verificar a imutabilidade da revisão Quando os requisitos operacionais mudarem, atualize a skill para criar uma nova revisão imutável: - Abrir detalhes da skill: no console, selecione "Incident Response Checklist" e clique em "New Revision". - Modificar instruções: adicione uma etapa obrigatória de verificação canary antes de reverter. - Salvar nova revisão: salvar o conteúdo incrementa o contador de revisão para v2, gerando um novo revision_id imutável e canonical_hash. - Proteção por fixação de revisão: fluxos de trabalho de agentes em andamento fixados na revisão v1 continuam lendo recursos v1 sem inconsistências, enquanto novas consultas de Nível 1 resolvem automaticamente a revisão v2 publicada. ## Resultado observável A criação e publicação bem-sucedidas de uma Cloud Skill produzem alterações observáveis no console e nas interfaces dos agentes: - Distintivo de status do console: o cartão da skill exibe o distintivo "Published", a tag de revisão ativa (como v1 ou v2) e a contagem de componentes. - Explorador de recursos: a visualização detalhada mostra o componente declarado templates/triage-template.md com pré-visualização de sintaxe e ações de cópia. - Envelope de recuperação do agente: o Nível 1 retorna uma resposta raiz tipada com instruction_body, revision_id e lista de recursos. O Nivel 2 retorna o texto exato do componente. - Disponibilidade de exportação: na visualização detalhada, clicar em "Export" baixa um arquivo ZIP Source Capsule contendo SKILL.md, metadados do manifesto e componentes declarados. ## O que os agentes podem acessar Agentes e usuários humanos operam sob limites estritos de autenticação e capacidade: - Perfis de cliente: as ferramentas MCP recall_cloud_skill e save_cloud_skill são expostas contratualmente nos perfis cursor-plugin e ordinary-full; perfis de cliente públicos e de chat genéricos não as expõem. - Aplicação de escopos: agentes se autenticam com chaves de API ou tokens OAuth contendo os escopos skills:read ou skills:write. Tokens vinculados à memória pessoal não podem inspecionar skills de equipe, a menos que estejam explicitamente associados a essa equipe. - Proteção de rascunhos e propostas: agentes não podem descobrir ou recuperar revisões de rascunho, revisões propostas aguardando revisão ou skills arquivadas na descoberta de consultas de Nível 0. - Orientação executável por prompt: agentes conectados interpretam instruções procedimentais diretamente como contexto de prompt; skills não executam código automaticamente no host. ## Limites de compartilhamento e ciclo de vida Cloud Skills mantém uma separação clara de locatários entre runbooks pessoais e ativos colaborativos de equipe: - Limites de espaço: skills pessoais (/me#skills) são privadas para o criador. Skills de equipe (?space=#skills) são compartilhadas com membros autenticados da equipe. - Aprovação de equipe: revisões de equipe exigem análise do proprietário ou administrador antes da transição do status "proposed" para "published". - Arquivamento versus exclusão: arquivar uma skill (DELETE /v1/skills/{skill_id}) desativa a descoberta por agentes e a oculta da lista ativa, preservando o histórico imutável de revisões. - Imutabilidade de revisões: revisões são snapshots imutáveis endereçados por conteúdo; salvar atualizações cria uma nova revisão em vez de sobrescrever registros existentes. - Banner de revisão de candidatos: o console pode exibir um banner de candidato com ações Promote e Dismiss quando existir um candidato; candidatos exigem revisão manual. ## Recuperação de falhas Diagnostique e resolva problemas comuns de Cloud Skills usando as seguintes etapas de remediação: - Erro de recuperação de recurso (REVISION_PINNING_VIOLATION): solicitações de recursos de Nível 2 exigem um revision_id explícito. Se omitido, o servidor recusa a solicitação para evitar inconsistências de recursos. Correção: informe o revision_id retornado na resposta de Nível 1. - Skill não encontrada (SKILL_NOT_FOUND): verifique se o slug corresponde exatamente e se a consulta é executada no espaço de trabalho correto (Personal versus Team ?space=). - Acesso negado (403 Forbidden): verifique se o token do agente inclui skills:read (para recuperação) ou skills:write (para salvamento), e se o usuário autenticado pertence à equipe de destino. - A revisão de equipe permanece no estado proposto: um agente que consulta uma skill de equipe recebe a revisão atualmente publicada até que um proprietário ou administrador da equipe revise e publique a revisão proposta. - Ambiente de execução indisponível (503): retornado se o subsistema Cloud Skills estiver desabilitado ou não configurado em seu ambiente de implantação. ## Referência relacionada Consulte a documentação relacionada para arquitetura conceitual, parâmetros de ferramentas e colaboração em equipe: - Conceitos de Cloud Skills: /docs/concepts/cloud-skills para arquitetura de três camadas, modelos de componentes e fixação de revisões. - Referência de recall_cloud_skill: /docs/tools/recall-cloud-skill para esquemas de parâmetros e formatos de resposta. - Referência de save_cloud_skill: /docs/tools/save-cloud-skill para parâmetros de autoria e formatos de upload de componentes. - Memory Console: /docs/guides/memory-console para layout do console web, seleção de espaço e configurações. - Teams: /docs/capabilities/teams para colaboração em espaços de trabalho de equipe e permissões de papéis. ## 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.