Spark CLI Skills
spark-cli-skills
Skills for Spark mail: a CLI command reference, 25 ready workflows and 8 roles, from executive assistant to support agent.
- 156 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The skills read mail, calendar, contacts and meeting transcripts, which are personal data.
- At the `send` access level the agent sends mail and invitations on your behalf.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/spark-cli-skillsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The skills read mail, calendar, contacts and meeting transcripts, which are personal data.
- At the `send` access level the agent sends mail and invitations on your behalf.
This is third-party code. Review the repository files before installing.
What it does
spark-cli-skills are Readdle's official skills for the `spark` command line, which links an agent to the Spark Desktop mail client. The base skill `use-spark` holds a reference for commands and filters across mail, calendar, contacts, teams and meeting transcripts. The other 33 skills build on it. 25 workflow skills ("recipes") each solve one task: a morning briefing, inbox to zero, meeting prep, follow-up emails after a meeting, finding free time, newsletter cleanup, shared inbox triage. 8 roles ("personas") set a working style for a whole session: executive assistant, founder, team lead, project manager, sales rep, support agent, meeting manager and freelancer. Install the whole set or one skill at a time.
Who it is for. Spark users on macOS and Windows who hand mail and calendar triage to an agent and want to set an access level for each account.
Good fit when
- Mornings need one briefing: the day's events, unread mail by category and team assignments.
- Mail piled up during a vacation and is processed in batches by category.
- Context is gathered for a meeting, and follow-up emails with action items are written from its transcript.
- A shared support inbox is worked through: assigning owners, replying and closing items.
- Subscriptions and notifications are cleaned up: senders blocked, unsubscribes sent, mail archived.
Not a fit when
- Spark Desktop is not installed: the CLI talks to the app on your computer and does not work without it.
- The agent runs in a sandbox, container or CI: from isolation `spark` cannot reach the app.
- Your mail lives in another client: the skills are written only for the Spark CLI.
Example request
Build a morning briefing: today's events, unread mail by category and the tasks assigned to me in the team.Limitations
A recent Spark Desktop for macOS or Windows with at least one signed-in account and an enabled CLI are required: in Spark settings, the AI Agents section, then Spark CLI Setup. Each account and shared inbox gets an access level: `read-only`, `triage` (drafts, comments, actions on mail and contacts) or `send` (sending mail and invitations). A workflow that lacks the level returns an error explaining how to raise it. The CLI works through the running app, so the agent cannot run in a sandbox, container or CI. If Spark Desktop is closed, the agent asks you to open it. The license is MIT.
How to disable. Delete the `use-spark`, `recipe-*` and `persona-*` directories from the agent's skills folder. Switch CLI access off in Spark Desktop settings, the AI Agents section, or lower the account level to `read-only`.
FAQ
How do I install spark-cli-skills?
Enable the CLI in Spark Desktop and run `npx skills add https://github.com/readdle/spark-cli-skills`. A single skill installs by its folder address, for example `.../tree/main/skills/use-spark`.
What should I install if I do not need the whole set?
`use-spark` is required: every workflow depends on it. Add the `recipe-*` skills you need and, if you like, one `persona-*` role.
How do the access levels differ?
`read-only` reads mail, calendar and contacts. `triage` adds drafts, comments and actions on mail. `send` allows sending mail and invitations.
Can the agent send an email on its own?
Only on an account with the `send` level. Under `read-only` and `triage`, sending and event operations return an error.
Do the skills work on Linux?
No. You need Spark Desktop for macOS or Windows, and the CLI connects to the running app.
Discussion
No questions or reviews yet.
Related
Skillscafe3310's personal skill collection: spec-driven project work, reviews, reports, browser, 3D and video in one repository
A set of 13 SKILL.md skills: research, a product doc, decks, articles and audits for any compatible agent
A collection of skills for decisions and projects: strategy, market research, thinking, data analysis, docs and slides.
Lark CLI
lark-cli
The official Lark and Feishu CLI with agent skills: messages, docs, sheets, calendar, mail and tasks from the terminal, over 200 commands
Twenty-seven Chinese-language skills for development, thinking, learning, writing, visuals, branding and working with agents
37signals skills teach an agent to work in Basecamp, HEY and Fizzy through each product command line client
README in short
The repository carries manifests for Codex (`.codex-plugin`) and Cursor (`.cursor-plugin`), so the set installs through more than `npx skills`. Copyright belongs to Spark Mail Limited and the license is MIT.
README badge
Original SKILL.md
---
name: use-spark
description: >-
Use the spark CLI to access the user's Spark email data - list emails,
search by topic, read threads, check calendar events, find availability,
look up contacts, and view team info. Use when the user asks about their
emails, calendar, contacts, meetings, or scheduling.
metadata:
version: 1.4.1
requires:
bins:
- spark
---
# Using spark
`spark` is a CLI for the Spark email client. Use it to query the user's mailbox, calendar, contacts, meetings, and team data.
## Running spark
```bash
spark <command> [options]
```
**Environment:** `spark` is a thin client that talks over IPC to the user's running Spark Desktop app - it does not ship its own mailbox, network stack, or credentials. Run it directly on the user's computer against the live Spark Desktop process. Do not try to execute it inside a sandbox, container, CI runner, or any environment isolated from the user's desktop session - it will fail to connect. If Spark Desktop is not running, ask the user to launch it instead of retrying.
**JSON output:** add `--json` to any command to get its result as JSON instead of text - the same data, with full (untruncated) values, snake_case keys, and ISO 8601 dates. A failure prints `{"error": {"message": "…"}}` on stdout and exits non-zero. Prefer the default text when you only need to read the result; use `--json` when you need to process it (e.g. `spark emails --json | jq '.emails[].id'`). Fields are only ever added, never renamed or removed.
## Commands
| Command | Description |
|---------|-------------|
| `accounts` | List accounts, calendars, teams, shared inboxes, and access levels |
| `folders` | List folders/labels with message counts |
| `emails` | List emails with filters and pagination |
| `search` | Hybrid keyword + semantic search with full bodies |
| `thread` | Read full thread - headers, bodies, attachments |
| `attachment` | Read a single email attachment by its ID (auto-downloads) |
| `draft` | Create, edit, or delete an email draft (new, reply, forward, from template), or list account signatures |
| `templates` | List saved message templates (personal and team) |
| `template` | Show a single template by ID or name with its placeholders |
| `comment` | Post a team comment on a thread |
| `events` | List calendar events for a time range |
| `event` | Create, update, delete, or RSVP to a calendar event, including managing attendees / invitations |
| `availability` | Find free time slots, optionally with attendees |