# Cloud Skills

Author, review, publish, and progressively recall reusable procedural skills across connected agents.

- Canonical: https://docs.xmemo.dev/docs/guides/cloud-skills
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 260277857474b16f5cd72561cc55c36ba9d7592b3c223cfb9fba22a647faea9b
- Edition-Digest: 535d71c5f596f75afbf889e86dba034c1fc99c2440b20693535192bb6a2d0d6d
- Source-Revision: sha256:12bf6ae7b51cac41c1860d2f68cd5a3b7f9c37d20450d85946c4e31cd8d59b8a

## User goal

Author, review, publish, and recall reusable procedural skills (such as runbooks, checklists, and standard operating procedures) across connected agents without manual copy-pasting, repeated per-agent setup, or context window bloat.

## Availability and prerequisites

Cloud Skills is currently in Preview in the Memory Console at https://xmemo.dev/me#skills. Ensure your environment meets the following requirements before authoring or recalling skills:

- Feature enablement: Active when procedural Cloud Skills is enabled for your account.
- Workspace selection: Personal space (https://xmemo.dev/me#skills) stores private skills. Team space (https://xmemo.dev/me?space=<team_id>#skills) shares skills across authenticated team members with role-based governance.
- Agent token scopes: Agent recall requires skills:read or memory:read scope. Skill creation and revision publishing require skills:write or memory:write scope.
- Supported client profiles: MCP tools recall_cloud_skill and save_cloud_skill are exposed in the cursor-plugin and ordinary-full client profiles; generic public and chat interfaces do not expose skill authoring tools directly.

## 1. Navigate to Cloud Skills in Memory Console

Open the Memory Console and select the Cloud Skills section:

- Personal space: Open https://xmemo.dev/me#skills to manage your personal procedural runbooks.
- Team space: Open https://xmemo.dev/me?space=<team_id>#skills to manage shared organizational skills.
- Console interface: The panel displays the skills list, search bar ("Search skills by name, slug, or keywords..."), and primary actions: "New Skill" and "Import Skill".

## 2. Author a procedural skill and declared components

Click "New Skill" to open the skill authoring modal. Configure the skill metadata, root instructions, and component resources:

- Skill Name: Enter "Incident Response Checklist" (required field).
- Slug: Enter a lowercase identifier "incident-response-checklist" (1–64 alphanumeric characters or hyphens).
- Description: Enter "Standard operating procedure for triaging and resolving high-severity production incidents.".
- Instructions: Author root procedural guidance in markdown (limited to 64 KiB UTF-8).
- Components: Add template component templates/triage-template.md with type template containing the incident questionnaire.

```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. Review and publish the skill revision

Save the skill revision and observe how publishing behaves across personal and team spaces:

- Personal publishing: In a personal workspace, saving with publish intent transitions revision v1 directly to "Published", making it immediately discoverable to authorized agents.
- Team review workflow: In a team workspace, saving creates revision v1 with status "proposed". Team members can review the instructions, inspect component diffs, and test execution before a team owner or admin publishes the revision.
- Draft staging: If publish intent is unchecked, the revision remains in "Draft" status for private editing and testing without exposing it to agent discovery.

## 4. Verify agent progressive recall

Connected agents query and retrieve published skills on demand across three progressive levels to preserve context budgets:

- Level 0 (Discovery): Agent searches by task query and receives lightweight descriptors without full instructions.
- Level 1 (Root instructions): Agent recalls root instructions and the component manifest using the skill slug.
- Level 2 (Pinned resource): Agent retrieves the declared template component by supplying the exact revision_id returned from Level 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="<revision-id-from-level-1>",
  resource="templates/triage-template.md",
)
```

## 5. Update procedure and verify revision immutability

When operational requirements change, update the skill to create a new immutable revision:

- Open skill detail: In the console, select "Incident Response Checklist" and click "New Revision".
- Modify instructions: Add a mandatory canary verification step before rolling back.
- Save new revision: Saving content increments the revision counter to v2, generating a new immutable revision_id and canonical_hash.
- Revision pinning protection: Ongoing agent workflows pinned to revision v1 continue to read v1 resources without tearing, while new Level 1 queries automatically resolve the published v2 revision.

## Observable result

A successful Cloud Skill creation and publication produces observable changes across the console and agent interfaces:

- Console status badge: The skill card displays the "Published" badge, active revision tag (such as v1 or v2), and component count.
- Resource Explorer: The detail view shows the declared templates/triage-template.md component with syntax preview and copy actions.
- Agent recall envelope: Level 1 returns a typed root response with instruction_body, revision_id, and resources list. Level 2 returns the exact component text.
- Export availability: From the detail view, clicking "Export" downloads a Source Capsule ZIP archive containing SKILL.md, manifest metadata, and declared components.

## What agents can access

Agents and human users operate under strict authentication and capability boundaries:

- Client profiles: The MCP tools recall_cloud_skill and save_cloud_skill are contractually exposed in the cursor-plugin and ordinary-full profiles; generic public and chat client profiles do not expose them.
- Scope enforcement: Agents authenticate with API keys or OAuth tokens carrying skills:read or skills:write scopes. Tokens scoped to personal memory cannot inspect team skills unless explicitly bound to that team.
- Draft and proposed protection: Agents cannot discover or recall draft revisions, proposed revisions awaiting review, or archived skills in Level 0 query discovery.
- Prompt-executable guidance: Connected agents interpret procedural instructions directly as prompt context; skills do not execute code automatically on the host.

## Sharing and lifecycle boundaries

Cloud Skills maintain clear tenant separation between personal runbooks and collaborative team assets:

- Space boundaries: Personal skills (/me#skills) are private to the creator. Team skills (?space=<team_id>#skills) are shared with authenticated team members.
- Team approval: Team revisions require owner or admin review before transition from proposed to published status.
- Archiving vs deletion: Archiving a skill (DELETE /v1/skills/{skill_id}) disables agent discovery and hides it from the active list while preserving immutable revision history.
- Revision immutability: Revisions are immutable content-addressed snapshots; saving updates creates a new revision rather than overwriting existing records.
- Candidate review banner: The console can display a candidate banner with Promote and Dismiss actions when a candidate exists; candidates require manual review.

## Failure recovery

Diagnose and resolve common Cloud Skill issues using the following remediation steps:

- Resource recall error (REVISION_PINNING_VIOLATION): Level 2 resource requests require an explicit revision_id. If omitted, the server refuses the request to prevent resource tearing. Fix: Pass the revision_id returned in the Level 1 response.
- Skill not found (SKILL_NOT_FOUND): Verify that the slug matches exactly and that the query is executed in the correct workspace (Personal vs Team ?space=<team_id>).
- Access denied (403 Forbidden): Check that the agent token includes skills:read (for recall) or skills:write (for saving), and that the authenticated user belongs to the target team.
- Team revision remains in proposed state: An agent querying a team skill receives the currently published revision until a team owner or admin reviews and publishes the proposed revision.
- Runtime unavailable (503): Returned if the Cloud Skills subsystem is disabled or unconfigured in your deployment environment.

## Related reference

Consult related documentation for conceptual architecture, tool parameters, and team collaboration:

- Cloud Skills concepts: /docs/concepts/cloud-skills for three-tier architecture, component models, and revision pinning.
- recall_cloud_skill reference: /docs/tools/recall-cloud-skill for parameter schemas and response formats.
- save_cloud_skill reference: /docs/tools/save-cloud-skill for authoring parameters and component upload formats.
- Memory Console: /docs/guides/memory-console for web console layout, space selection, and settings.
- Teams: /docs/capabilities/teams for team workspace collaboration and role permissions.

## ChatGPT user

Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.

Connect the hosted XMemo MCP server through the ChatGPT/OpenAI app OAuth flow, then approve the memory:read and memory:write grant for your XMemo account.

Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.

If OAuth fails or tools do not appear, sign out of the MCP server in the host app, reconnect the XMemo server URL, and retry before creating direct tokens.

## Copilot / Codex developer

Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.

Use OAuth for VS Code / GitHub Copilot and Gemini CLI when available. For Copilot CLI, Codex, Cursor, or other direct MCP clients, keep XMEMO_KEY in the local environment or secret store and set a stable XMEMO_AGENT_INSTANCE_ID.

Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.

If recalls are empty, verify the selected MCP config path, the XMEMO_KEY environment variable for direct clients, and any stale OAuth credential in the host app.

## Team / enterprise pilot owner

Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.

Create or enter the protected XMemo workspace, invite approved users, then connect each client through OAuth or a scoped direct credential according to the readiness badges.

Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.

If a member cannot connect, check role permissions, OAuth approval, client readiness status, and support guidance before issuing a new token.

## Autonomous agent operator

Let headless or scheduled agents record progress, retrieve prior decisions, and keep a stable non-secret instance identity.

Fetch /api/v1/mcp/config/autonomous-agent. Prefer auth_modes.oauth when the runner supports OAuth + custom headers; use auth_modes.xmemo_key with XMEMO_KEY from a secret store only for fully headless runners.

Run one synthetic task that writes progress to XMemo, restart the runner, and confirm it recalls that progress using the same XMEMO_AGENT_INSTANCE_ID.

If attribution changes or recalls split across instances, persist XMEMO_AGENT_INSTANCE_ID outside git and verify the runner is not regenerating it on every start.