Skills

Skills are Markdown-based extensions that teach Mercury how to do a specific task. Each skill is a single SKILL.md file in ~/.mercury/skills/<name>/ and follows the Agent Skills specification.

A skill bundles:

• Frontmatter describing the skill, its tags/intents, and which tools it is allowed to call.
• Markdown instructions that get injected into Mercury's context when the skill is invoked.
• Optional scripts/ and references/ subdirectories that the skill can read at runtime.

Where skills live

~/.mercury/skills/
├── _template/        # Seeded template you can copy
├── web-search/       # Seeded default skill
└── <your-skill>/
    ├── SKILL.md
    ├── scripts/      # optional
    └── references/   # optional

On first run, Mercury seeds a _template directory and a curated set of built-in skills. If a seeded SKILL.md already exists, it is left alone — your customizations are never overwritten.

Bundled default skills

As of v1.1.11, fresh installs (or mercury doctor --seed-skills) come with three built-in skills:

Skill	What it does	Tools used
web-search	DuckDuckGo HTML search + summarized sources with cross-referencing.	fetch_url
tweet-notifier	Schedule tweets with founder approval and supporter notifications.	schedule_task, send_message, save_memory, search_memory, fetch_url, github_api
screenshot	Full-page website screenshots via Playwright with configurable viewport (mobile/desktop/HD/custom) and dark/light color scheme. Output goes to ~/Desktop/<domain>-<timestamp>.png.	run_command, create_file, write_file, send_file, cd, send_message

The screenshot skill requires Playwright/Chromium (npx playwright install chromium). On Telegram, the captured image is sent as a photo attachment.

Browse and install community skills at skills.mercuryagent.sh.

SKILL.md format

---
name: daily-digest
description: Summarize the user's day from chat history and memory.
version: 0.1.0
category: productivity
categories:
  - productivity
  - reporting
intents:
  - daily summary
  - end of day report
tags:
  - digest
  - summary
allowed-tools:
  - read_file
  - list_dir
  - web_search
---

# Daily Digest

## What It Does

Generates a structured summary of the user's day from chat history and memory.

## Instructions

1. Read today's chat threads.
2. Pull memories created or referenced today.
3. Group by topic, list decisions made, and propose next-day priorities.

Required frontmatter

• name — unique slug across installed skills
• description — one-line summary used in listings and intent routing

Optional frontmatter

• version — semver string
• category / categories — used for grouping in the UI
• intents — natural-language hints used for automatic routing
• tags — arbitrary labels
• allowed-tools — the only tool names this skill may call when invoked (elevated permissions are granted from this list)

Mercury uses progressive disclosure: only the frontmatter and a short summary are kept in context until the skill is actually invoked, at which point the full Markdown body is loaded. This keeps token usage low even with many skills installed.

Installing skills

The fastest path is the Mercury Skills registry — a community catalog of 126+ vetted skills across 23 categories. Every skill on the registry has a public detail page you should review before installing; skills run with elevated permissions when invoked.

See the Skills command reference for the complete CLI / in-chat / dashboard / Telegram surface in one place. The summary below is a quickstart.

From the CLI (recommended)

The mercury skills command tree talks to the registry directly. No browser required.

# Discover
mercury skills categories                   # 23 categories
mercury skills browse finance-legal         # paginated list, with --page / --limit
mercury skills search "contract review"     # full-text search

# Inspect before installing
mercury skills view finance-legal/contract-review
mercury skills view finance-legal/contract-review --web    # opens the registry page
mercury skills view finance-legal/contract-review --raw    # prints raw SKILL.md

# Install / update / remove
mercury skills install finance-legal/contract-review
mercury skills install <id1> <id2> <id3>                    # batch
mercury skills install <id> --force                         # reinstall same version
mercury skills install --from ./local-skill.md              # install from a local file or URL
mercury skills update                                       # update all installed
mercury skills update finance-legal/contract-review         # update one
mercury skills remove finance-legal/contract-review

# Observability
mercury skills list                          # what's installed locally
mercury skills info                          # registry stats
mercury skills doctor                        # check registry reachability + cache

Shared flags:

• --json — emit machine-readable output (useful for scripting).
• --registry <url> — point at a different registry (also MERCURY_SKILLS_REGISTRY).
• -q, --quiet — suppress progress output.
• -y, --yes — skip confirmations.

Registry skills install into a nested layout to avoid name collisions:

~/.mercury/skills/
├── <category>/<slug>/SKILL.md     # registry skills (new)
├── _template/                     # seeded template
├── web-search/                    # legacy flat layout still works
└── .index.json                    # source of truth for `list` and `update`

The CLI never executes a skill's body during install — only writes the SKILL.md to disk after validating its frontmatter. Always review the registry page (mercury skills view <id> --web) before installing.

From the web dashboard

Open Skills in the dashboard at http://127.0.0.1:6174/skills.

• Install from registry — paste a category/slug id (e.g. finance-legal/contract-review) and click Install. The toast reports the install status (installed, updated, reinstalled, already-installed).
• Install from URL — paste a URL pointing to a raw SKILL.md. Mercury fetches it, validates the frontmatter, and saves it to disk.
• Use the toggle to activate or deactivate a skill without deleting it.
• Use the trash icon to delete a skill (removes its directory and its index entry).
• The header has a Browse skills.mercuryagent.sh link that opens the registry in a new tab.

From Telegram

If you've paired a Telegram bot, the /skills command is available to every approved user. Install is admin-only.

/skills                            # list installed skills + counts
/skills search <query>             # top 5 registry matches with their URLs
/skills view <id>                  # title, version, description, registry URL
/skills install <id>               # admin only — installs to ~/.mercury/skills/
/skills remove <id>                # admin only

Every result includes the https://skills.mercuryagent.sh/skills/<id> URL so you can review the skill on a real browser before installing it.

From chat

You can also tell Mercury in any channel:

• "Install skill from https://example.com/my-skill.md"
• Or paste the SKILL.md content directly into a message and ask Mercury to install it.

Manually

Drop a directory containing a valid SKILL.md into ~/.mercury/skills/ and Mercury will pick it up on its next discovery scan.

Invoking a skill

• Ask in natural language: "Use the daily-digest skill" — intent routing matches against the skill's intents, categories, and tags.
• Schedule it: "Remind me daily at 9am to run the daily-digest skill" — see the Schedules page.

When invoked, Mercury injects the skill's Markdown body into context as guidance, and the tools listed in allowed-tools are granted elevated permissions for the duration of that turn.

API

The web dashboard talks to the skill loader through these endpoints:

GET    /api/skills                          # list installed skills with active state
POST   /api/skills/install                  # { url } — fetch and install from a URL
POST   /api/skills/install-from-registry    # { id, force? } — install by registry id
POST   /api/skills/:name/activate
POST   /api/skills/:name/deactivate
DELETE /api/skills/:name

Writing your own

Copy the seeded template:

cp -r ~/.mercury/skills/_template ~/.mercury/skills/my-skill
$EDITOR ~/.mercury/skills/my-skill/SKILL.md

Edit the frontmatter (especially name, description, intents, and allowed-tools), rewrite the Markdown body, and the skill will be available on Mercury's next discovery scan. From the web dashboard, hit the refresh icon on the Skills page.

Tips

• Keep instructions concise — every token in the body is loaded when the skill is invoked.
• Only list the tools you actually need in allowed-tools (least-privilege).
• Use intents to make the skill discoverable from natural language without the user having to remember the exact name.
• Use scripts/ for reusable shell snippets and references/ for data files the skill can read.