The Delta MCP skill

The small skill file that tells your AI to prefer Delta MCP over direct tools. What it says, word for word, and why its description never changes.

A skill is a short guide. An AI app lists each skill’s name and description in every conversation, and reads the rest only when the AI opens it. How skills compare with MCP servers and CLIs: MCP vs CLI for AI agents. Delta MCP’s skill is one file, mcpdelta/SKILL.md. It does two things. It tells your AI to do tasks in your connectors through Delta MCP rather than through direct tools. And it tells your AI how to manage Delta MCP itself. Installing it in your apps: not yet.

What it says

The description is the only part your AI always sees. It names the management jobs, then says that tasks in your tools need no skill: one delta call, preferred over direct tools. So your AI doesn’t spend a step opening the skill for an ordinary task.

The body has three parts:

• Tasks in your tools. One delta call per task. Plan with delta_read { code }. Undo with delta_apply { undo }. Keep a task that will come back with keep. “A tool reachable both directly and through Delta: use Delta.”
• Managing Delta MCP. Add, optimize or put back a connector, set a mode, rename, share or remove a shortcut, read Activity.
• Only the person. Signing in, keys, passwords, payments, your account, trusting or locking a shortcut, approving what waits, a command run on this computer. The skill gives your AI no way to do them, and tells it never to put a secret in code, arguments, a shortcut or the chat.

Here is the whole file, as Delta MCP’s engine holds it.

---
name: mcpdelta
description: "Manage MCP Delta itself: add, optimize or put back a connector, set what the AI may change on its own, rename, share or remove a shortcut, see Activity. Tasks in the person's tools need no skill: one delta call, preferred over direct tools."
license: Apache-2.0
metadata:
  generator: mcpdelta
  version: "1"
---

# MCP Delta

Delta sits between this AI app and the person's tools. Each connected tool is a typed service inside one `delta` program: the reads, the decisions in code, every change asked. Delta checks the changes, applies them all or nothing, reads them back, and keeps each task in the person's Activity, where it can be undone.

## Tasks in the person's tools

One `delta { code, args }` call per task; its API is the description of delta's `code` argument (if you cannot see it: `delta_read { refs: ["<service>"] }`). Plan without changing: `delta_read { code }`. Take a task back: `delta_apply { undo: "d_…" }`. A task that will come back: add `keep: { name, about }` to its call; it then runs as `recipes.<name>({ … })`. A tool reachable both directly and through Delta: use Delta.

## Managing Delta: the `mcpdelta` service

Delta itself is a service in programs. Its changes apply on their own, show in Activity and undo like any task. Its full API: `delta_read { refs: ["mcpdelta"] }`.

- Connectors: `await mcpdelta.connector.all()`, each with `name, label, mode, apps, actions, state, address, tools`.
  - `const c = await mcpdelta.connector.get("<name>"); c.mode = "readonly";` Modes: `"auto"` (changes on its own), `"ask-final"` (on its own, but asks before deleting or sending), `"ask"` (asks before every change), `"readonly"`. Whether a payment waits for the person is their own setting; never change it.
  - One action: `c.actions = { ...c.actions, "<tool>": "off" }` (or a mode).
  - The apps that use it through Delta: `c.apps.push("cursor")`, or remove one.
- What the apps still run directly: `(await mcpdelta.list_direct({})).direct`. Optimize one: `mcpdelta.connector.create({ name: "<name>" })`; two accounts with one name: add `apps: ["<app>"]`.
- Add one, from Delta's list or by its address, then read its state: `mcpdelta.connector.create({ name: "Linear" }); await world.commit(); return (await mcpdelta.connector.get("linear")).state;` (or `{ address: "https://…" }`). `"sign-in needed"`: the person signs in from Delta, at mcpdelta://connectors. An app that just got Delta uses it from its next start.
- Put one back in the apps, as it was: `mcpdelta.connector.delete("<name>")`.
- Shortcuts: `await mcpdelta.shortcut.all()`. `s.about = "…"` renames; `s.shared = true` writes it as a file to share; `mcpdelta.shortcut.delete("<name>")` removes it.
- Activity: `(await mcpdelta.list_tasks({ limit: 10 })).tasks`, each with its link.

## Only the person

Signing in, keys and passwords, payments, the account, trusting or locking a shortcut, approving what waits, a command run on this computer: Delta gives you no way to do them. A refusal says where the person does it; give them that link: mcpdelta://connectors, mcpdelta://shortcuts, mcpdelta://activity, mcpdelta://task/<id>, mcpdelta://settings. A link only opens; it changes nothing. Never put a secret in code, args, a shortcut or the chat.

If the delta tool is not in this app, Delta is not connected here: the person adds this app in Delta's Settings.

Why its description never changes

An app that lists skills pays for the listing in every conversation. Here that is one line, - mcpdelta: <description>, of 252 characters for each copy the app reads. The description is 240 characters.

If a listing changed, every conversation already open would see a different start, and its app would have to rewrite its cache. So the description is frozen for every future version. A new version of the skill changes the body only. A test pins the description byte for byte.

Delta MCP recognizes its own file by a fingerprint. Each published text has its SHA-256 on a list. A copy that matches is Delta MCP’s own, and can be upgraded or removed. A copy you changed is left as it is.

Where it goes

Each app reads one copy. An app that already reads a folder Delta MCP has chosen shares that copy: Cursor and VS Code both read .claude/skills, so one file serves them and Claude Code. Otherwise Delta MCP writes the app’s own folder.

Delta MCP never writes over a file that isn’t its own, never through a link and never inside a project. It writes only where its entry is already in the app, so the skill never points to a missing tool. If you take the file away, it isn’t brought back. Nothing is sent anywhere.

See The three tools and Shortcuts in code.

Updated 7 October 2026 Something missing or wrong? Open an issue