Cloud Skills

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

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

{
  "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.