Guide de Cloud Skills

Objectif de l'utilisateur

Rédigez, révisez, publiez et rappelez des compétences procédurales réutilisables (telles que des runbooks, des listes de contrôle et des procédures opérationnelles standard) sur tous les agents connectés sans copier-coller manuel, configuration répétée par agent ni saturation de la fenêtre de contexte.

Disponibilité et prérequis

Cloud Skills est actuellement en Preview dans la Memory Console sur https://xmemo.dev/me#skills. Assurez-vous que votre environnement respecte les exigences suivantes avant de rédiger ou de rappeler des skills :

• Activation de la fonctionnalité : active lorsque procedural Cloud Skills est activé pour votre compte.
• Sélection de l'espace de travail : l'espace personnel (https://xmemo.dev/me#skills) stocke les skills privées. L'espace d'équipe (https://xmemo.dev/me?space=<team_id>#skills) partage les skills entre les membres authentifiés de l'équipe avec gouvernance basée sur les rôles.
• Portées de jeton d'agent : le rappel d'agent requiert la portée skills:read ou memory:read. La création de skills et la publication de révisions nécessitent la portée skills:write ou memory:write.
• Profils clients pris en charge : les outils MCP recall_cloud_skill et save_cloud_skill sont exposés dans les profils clients cursor-plugin et ordinary-full ; les interfaces publiques et de chat génériques n'exposent pas directement les outils de rédaction de skills.

1. Accéder à Cloud Skills dans la Memory Console

Ouvrez la Memory Console et sélectionnez la section Cloud Skills :

• Espace personnel : ouvrez https://xmemo.dev/me#skills pour gérer vos runbooks procéduraux personnels.
• Espace d'équipe : ouvrez https://xmemo.dev/me?space=<team_id>#skills pour gérer les skills organisationnelles partagées.
• Interface de console : le panneau affiche la liste des skills, la barre de recherche ("Search skills by name, slug, or keywords...") et les actions principales : "New Skill" et "Import Skill".

2. Rédiger une skill procédurale et les composants déclarés

Cliquez sur "New Skill" pour ouvrir la fenêtre de rédaction de skills. Configurez les métadonnées de la skill, les instructions racine et les ressources de composants :

• Skill Name : saisissez "Incident Response Checklist" (champ obligatoire).
• Slug : saisissez un identifiant en minuscules "incident-response-checklist" (1 à 64 caractères alphanumériques ou traits d'union).
• Description : saisissez "Standard operating procedure for triaging and resolving high-severity production incidents.".
• Instructions : rédigez les directives procédurales racine en markdown (limité à 64 KiB UTF-8).
• Components : ajoutez le composant de modèle templates/triage-template.md avec le type template contenant le questionnaire d'incident.

# 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. Réviser et publier la révision de la skill

Enregistrez la révision de la skill et observez le comportement de la publication entre espaces personnel et d'équipe :

• Publication personnelle : dans un espace de travail personnel, l'enregistrement avec intention de publication fait passer directement la révision v1 à "Published", la rendant immédiatement découvrable pour les agents autorisés.
• Flux d'examen en équipe : dans un espace de travail d'équipe, l'enregistrement crée la révision v1 avec le statut "proposed". Les membres de l'équipe peuvent examiner les instructions, inspecter les diffs de composants et tester l'exécution avant qu'un propriétaire ou administrateur d'équipe ne publie la révision.
• Phase de brouillon : si l'intention de publication n'est pas cochée, la révision reste au statut "Draft" pour modification et tests privés sans exposition à la découverte par les agents.

4. Vérifier le rappel progressif des agents

Les agents connectés interrogent et récupèrent les skills publiées à la demande selon trois niveaux progressifs afin de préserver les budgets de contexte :

• Niveau 0 (Découverte) : l'agent effectue une recherche par requête de tâche et reçoit des descripteurs légers sans les instructions complètes.
• Niveau 1 (Instructions racine) : l'agent rappelle les instructions racine et le manifeste de composants à l'aide du slug de la skill.
• Niveau 2 (Ressource épinglée) : l'agent récupère le composant de modèle déclaré en fournissant le revision_id exact renvoyé au Niveau 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. Mettre à jour la procédure et vérifier l'immuabilité de la révision

Lorsque les exigences opérationnelles évoluent, mettez à jour la skill pour créer une nouvelle révision immuable :

• Ouvrir le détail de la skill : dans la console, sélectionnez "Incident Response Checklist" et cliquez sur "New Revision".
• Modifier les instructions : ajoutez une étape obligatoire de vérification canary avant le rollback.
• Enregistrer la nouvelle révision : l'enregistrement du contenu incrémente le compteur de révision à v2, générant un nouveau revision_id immuable et canonical_hash.
• Protection par épinglage de révision : les flux d'agents en cours épinglés à la révision v1 continuent de lire les ressources v1 sans déchirement, tandis que les nouvelles requêtes de Niveau 1 résolvent automatiquement la révision v2 publiée.

Résultat observable

La création et publication réussies d'une Cloud Skill produisent des changements observables sur la console et les interfaces d'agents :

• Badge de statut de la console : la carte de skill affiche le badge "Published", la balise de révision active (telle que v1 ou v2) et le nombre de composants.
• Explorateur de ressources : la vue détaillée affiche le composant déclaré templates/triage-template.md avec aperçu de syntaxe et actions de copie.
• Enveloppe de rappel d'agent : le Niveau 1 renvoie une réponse racine typée avec instruction_body, revision_id et liste de ressources. Le Niveau 2 renvoie le texte exact du composant.
• Disponibilité d'exportation : depuis la vue détaillée, cliquer sur "Export" télécharge une archive ZIP Source Capsule contenant SKILL.md, les métadonnées du manifeste et les composants déclarés.

Ce à quoi les agents peuvent accéder

Les agents et les utilisateurs humains opèrent selon des frontières strictes d'authentification et de capacités :

• Profils clients : les outils MCP recall_cloud_skill et save_cloud_skill sont contractuellement exposés dans les profils cursor-plugin et ordinary-full ; les profils clients génériques publics et de chat ne les exposent pas.
• Application des portées : les agents s'authentifient avec des clés API ou jetons OAuth disposant des portées skills:read ou skills:write. Les jetons limités à la mémoire personnelle ne peuvent pas inspecter les skills d'équipe à moins d'être explicitement liés à cette équipe.
• Protection des brouillons et propositions : les agents ne peuvent pas découvrir ni rappeler les révisions en brouillon, les révisions proposées en attente d'examen ou les skills archivées lors de la découverte de requêtes de Niveau 0.
• Directives exécutables par prompt : les agents connectés interprètent les instructions procédurales directement comme contexte de prompt ; les skills n'exécutent pas de code automatiquement sur l'hôte.

Frontières de partage et de cycle de vie

Cloud Skills maintient une séparation claire des locataires entre runbooks personnels et ressources d'équipe collaboratives :

• Frontières d'espace : les skills personnelles (/me#skills) sont privées pour le créateur. Les skills d'équipe (?space=<team_id>#skills) sont partagées avec les membres authentifiés de l'équipe.
• Approbation d'équipe : les révisions d'équipe nécessitent l'examen d'un propriétaire ou administrateur avant de passer du statut "proposed" à "published".
• Archivage vs suppression : archiver une skill (DELETE /v1/skills/{skill_id}) désactive la découverte par les agents et la masque de la liste active tout en préservant l'historique immuable des révisions.
• Immuabilité des révisions : les révisions sont des instantanés immuables adressés par le contenu ; l'enregistrement des mises à jour crée une nouvelle révision plutôt que d'écraser les enregistrements existants.
• Bannière d'examen de candidat : la console peut afficher une bannière de candidat avec les actions Promote et Dismiss lorsqu'un candidat existe ; les candidats nécessitent un examen manuel.

Dépannage

Diagnostiquez et résolvez les problèmes courants de Cloud Skills à l'aide des étapes correctives suivantes :

• Erreur de rappel de ressource (REVISION_PINNING_VIOLATION) : les requêtes de ressources de Niveau 2 nécessitent un revision_id explicite. S'il est omis, le serveur refuse la requête pour éviter le déchirement de ressource. Solution : transmettez le revision_id renvoyé dans la réponse de Niveau 1.
• Skill introuvable (SKILL_NOT_FOUND) : vérifiez que le slug correspond exactement et que la requête est exécutée dans l'espace de travail approprié (Personal vs Team ?space=<team_id>).
• Accès refusé (403 Forbidden) : vérifiez que le jeton d'agent inclut skills:read (pour le rappel) ou skills:write (pour l'enregistrement), et que l'utilisateur authentifié appartient à l'équipe cible.
• La révision d'équipe reste à l'état proposé : un agent interrogeant une skill d'équipe reçoit la révision actuellement publiée jusqu'à ce qu'un propriétaire ou administrateur d'équipe examine et publie la révision proposée.
• Runtime indisponible (503) : renvoyé si le sous-système Cloud Skills est désactivé ou non configuré dans votre environnement de déploiement.

Références associées

Consultez la documentation connexe pour l'architecture conceptuelle, les paramètres d'outils et la collaboration en équipe :

• Concepts Cloud Skills : /docs/concepts/cloud-skills pour l'architecture à trois niveaux, les modèles de composants et l'épinglage de révision.
• Référence recall_cloud_skill : /docs/tools/recall-cloud-skill pour les schémas de paramètres et formats de réponse.
• Référence save_cloud_skill : /docs/tools/save-cloud-skill pour les paramètres de rédaction et formats de téléversement de composants.
• Memory Console : /docs/guides/memory-console pour la disposition de la console web, la sélection de l'espace et les paramètres.
• Teams : /docs/capabilities/teams pour la collaboration dans l'espace de travail d'équipe et les autorisations de rôle.