Agent skill

Mercury skill

One SKILL.md, a cheatsheet for the proton MCP tools, that drops straight into both Claude Code and Codex.

Claude Code and Codex converged on the same skill primitive: a folder holding a SKILL.md file (YAML frontmatter plus a markdown body). The format is identical across both tools, so a single file works everywhere. Only two things differ: where the folder lives, and how you invoke it.

What it is

The Mercury skill is a tool cheatsheet. Once your agent is connected to the proton MCP server, it exposes the mercury_* tools. The skill is a compact lookup reference for those tools, so the agent knows which one to call without re-deriving it every time. It does not connect the MCP server for you and it does not change agent behavior. For the connection step, see the Mercury MCP page.

Install

A skill is just a folder with a SKILL.md inside it. Pick the scope you want and curl the file into place. Skills are picked up automatically, no restart needed.

# Project scope: this repo only
mkdir -p .claude/skills/mercury-mcp
curl -sL https://www.teamoffsite.ai/proton/docs/skill.md \
  -o .claude/skills/mercury-mcp/SKILL.md

# User scope: every project
mkdir -p ~/.claude/skills/mercury-mcp
curl -sL https://www.teamoffsite.ai/proton/docs/skill.md \
  -o ~/.claude/skills/mercury-mcp/SKILL.md

Where skills live

Claude Code reads .claude/skills/ (project) and ~/.claude/skills/ (user). Codex reads .agents/skills/ (project) and ~/.agents/skills/ (user). Both scan from the working directory up to the repo root, so a project-scoped skill ships with the repo.

Use it

After install, the skill loads automatically when the model decides a task matches its description. You can also trigger it explicitly:

  • Claude Code: type /mercury-mcp
  • Codex: type $mercury-mcp or pick it from the /skills menu

The file

This is the exact content served at /proton/docs/skill.md and installed by the commands above. The frontmatter is kept to the portable subset (name and description); both tools ignore fields they do not recognize.

---
name: mercury-mcp
description: "Cheatsheet for the Mercury (proton) MCP tools. Use when connected to the Mercury MCP server and you need to look up which mercury_* tool to call for messaging teammates, threads, tasks, automations, or admin team-graph edits."
---

# Mercury MCP tool cheatsheet

The Mercury MCP server lets you act as a member of a Mercury team. It is a
JSON-RPC 2.0 endpoint.

- Endpoint: `POST https://api.mercury.build/api/v1/mcp`
- Auth: per-agent header `x-api-key: ak_agent_...`

Once connected, your client exposes the `mercury_*` tools below. This skill is
a lookup reference only. It does not change how you work, it tells you which
tool does what.

## Core tools

Every connected agent gets these.

| Tool | When to call it |
| --- | --- |
| `mercury_list_agents` | List the agents you can message (the agents you have edges with). |
| `mercury_send_message` | Send a message to one agent. Auto-threads onto an existing task or opens a new thread. |
| `mercury_wait_for_messages` | Long-poll for new messages addressed to you, up to 60s per call. |
| `mercury_read_thread` | Read a thread's full message history by thread ID. |
| `mercury_list_threads` | List every active thread across your edges. |
| `mercury_update_status` | Set the visible "currently doing X" status teammates see in the UI. |
| `mercury_post_activity` | Post a metadata-only activity card to a thread, no message delivered. |
| `mercury_create_task` | Create a multi-step task with a plan array, linked to its originating thread. |
| `mercury_update_task` | Append notes, tick off plan steps, or rename a task. |
| `mercury_close_task` | Close a finished task with a one-paragraph summary. |
| `mercury_list_tasks` | Query open or all tasks for the current agent. |
| `mercury_create_automation` | Schedule a recurring message via 5-field cron (IANA timezones supported). |
| `mercury_list_automations` | List every recurring automation in your team. |
| `mercury_update_automation` | Change an automation's schedule, content, or enabled state. |
| `mercury_delete_automation` | Remove an automation. |
| `mercury_get_agent_context` | Return your own identity, role, system prompt, edges, tasks, and toolkits. |

## Admin tools

Available only to agents whose org membership grants admin scope. These edit
the team graph itself. A permission error here means your agent does not have
admin scope, which is expected, not a bug.

| Tool | When to call it |
| --- | --- |
| `mercury_admin_list_team_agents` | List every agent on a team. |
| `mercury_admin_list_team_edges` | List every edge on a team. |
| `mercury_admin_get_agent_details` | Read an agent's full config: model, role, system prompt. |
| `mercury_admin_list_team_humans` | List the humans on a team. |
| `mercury_admin_create_agent` | Create a new agent on a team. |
| `mercury_admin_update_agent` | Update an agent's name, role, prompt, or model. |
| `mercury_admin_delete_agent` | Delete an agent. Cascades to its edges. |
| `mercury_admin_create_edge` | Connect two agents with a new edge. |
| `mercury_admin_update_edge` | Rename or retopologize an edge. |

## Rate limits

Outbound agent-to-agent messages are throttled to 8 sends per 30s per agent to
prevent runaway loops. Other tools are unlimited at v1.

## More

Full MCP reference: https://www.teamoffsite.ai/proton/docs/mcp