Skills

Skills

Last Updated: 2026-06-22 | Version: 1.1.0

Changelog:

• v1.1.0 — Reconcile drift (#218): bundled unsubscribe-cleanup version 0.1.1 → 0.1.2; added version header.
• v1.0.0 — Initial Skills page.

Skills are markdown instructions that teach Claude how to use this MCP's tools for specific workflows. They ship bundled with the .mcpb, auto-install to ~/.claude/skills/imap-mcp-pro/, and can be updated from this repo without reinstalling the extension.

Where to find the canonical guide

The full reference lives in the repo at docs/SKILLS.md. It's versioned alongside the code, so it's always accurate for the release you're running.

Topics covered there:

• TL;DR — what skills are, what they aren't
• Auto-install behavior at server startup
• The two update tools: imap_check_skill_updates and imap_update_skills
• Trust model — manual confirmation, manifest-as-allowlist, user-edit preservation
• Configuration via environment variables
• Troubleshooting common errors
• Contributor guide for adding a new skill
• Architecture rationale (why bundled, why markdown, why allowlisted)

Quick reference

Need to...	How
See what skills are installed	ls ~/.claude/skills/imap-mcp-pro/
Check for updates	Ask Claude: "Are there any updates available for my imap-mcp-pro skills?"
Apply an update	Ask Claude: "Update the unsubscribe-cleanup skill"
Disable auto-install	Set IMAP_MCP_SKIP_SKILLS_INSTALL=1
Use a fork or private repo	Set IMAP_MCP_SKILL_GITHUB_REPO=<owner>/<repo> and optionally IMAP_MCP_GITHUB_TOKEN
Add a new skill	See the contributor guide

Currently bundled

Skill	Version	Description
unsubscribe-cleanup	0.1.2	Find newsletter senders, present candidates for review, execute unsubscribes safely. Gmail-aware.

Future skills (planned, not yet shipped): email-triage, correspondence-research.

Trust model — short version

Skills are instructions to the LLM. Whoever controls the source repo controls how Claude behaves. To preserve user agency:

• Updates never automatic — every change requires explicit user request.
• The bundled manifest.json acts as the allowlist — only known skills can be installed.
• User edits are preserved when the on-disk version is bumped above the source.
• Default source is this MCP's own public repo, no third-party trust required.

Always run imap_check_skill_updates before applying. Review the available URL in the response if you want to eyeball the diff before invoking imap_update_skills.

See also

• docs/SKILLS.md — full guide
• CHANGELOG.md — version history including skill changes (search for "skill")
• Issue #138 — the v2.17.4 design discussion that introduced the update tools
• Issue #120 — the broader skill-installer design tracker