Guia de Cloud Skills

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=<team_id>#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=<team_id>#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.

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

# 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="<revision-id-from-level-1>",
  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=<team_id>#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=<team_id>).
• 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.