mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-16 22:16:52 +03:00
3256a87bcb
Adds five top-level operational tool skills, one per named tool: - slack: messages, channels, threads, search, files, and webhook signature verification (HMAC-SHA256) via a bounded, stdlib-only slack-cli. - notion: pages, database queries, search, and guarded page updates via notion-cli. - email: transactional email via Twilio SendGrid (send, deliverability bounces/spam reports, Signed Event Webhook verification with a self-contained ECDSA P-256 verifier) via email-cli. - crm: HubSpot CRM records, contact search, and deal pipeline views with guarded stage updates via crm-cli. - stripe: read-only-first balance, payment, and subscription queries with a guarded period-end subscription cancellation via stripe-cli. Each skill ships an executable script (--json output, --limit bounded reads, --dry-run/--yes mutation gate), a human README with the five required sections, a schema-v1 evals/evals.json with six output-quality cases, a dated source index + operations reference, and a deterministic unittest suite run by check-artifacts. All five are indexed in the top-level README and the generated catalogs were regenerated. Eval coverage rises from 78/139 to 83/144. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
123 lines
9.3 KiB
Markdown
123 lines
9.3 KiB
Markdown
---
|
|
name: slack
|
|
description: >-
|
|
Operate Slack workspaces from a terminal or agent: list channels, read
|
|
messages, follow threads, search message history, list files, and verify
|
|
inbound webhook signatures — with a bundled slack-cli script that is
|
|
read-only by default and gates every send behind a --dry-run/--yes
|
|
confirmation. Use when an agent needs to read or post Slack data, triage
|
|
incidents, or answer questions about what was said in a workspace. Do not
|
|
use for building Slack apps or bots (that is application development) or
|
|
workspace administration like user provisioning and org settings (that is
|
|
the Slack admin console).
|
|
license: MIT
|
|
compatibility: >-
|
|
The bundled slack-cli script runs on Python 3.9+ with only the standard
|
|
library. --help, channel/message/thread/search/file reads, and webhook
|
|
signature verification need no network; live reads require a Slack bot/user
|
|
token with the right scopes and network access to api.slack.com.
|
|
metadata:
|
|
source: https://api.slack.com/web
|
|
source_index: references/00-source-index.md
|
|
research_checked: "2026-08-03"
|
|
---
|
|
|
|
# Slack Operations
|
|
|
|
Use this skill to read and, with explicit confirmation, write Slack data through the Slack Web API: channels, messages, threads, search, files, and webhook signature verification. This is a **tool skill** for the Slack platform. Building Slack apps and bots is application development; workspace administration (user provisioning, org-level settings, SSO) lives in the Slack admin console. This skill owns the everyday agent workflow: knowing what was said, finding it later, and posting a reply when a human confirms.
|
|
|
|
## Operating contract
|
|
|
|
1. **Read-only discovery before any mutation.** List channels, read history, follow threads, search, and list files freely. The bundled `slack-cli` script makes reads without writing anything.
|
|
2. **Confirm the target, scope, and rollback path before acting.** Sending a message or replying in a thread changes shared workspace state visible to everyone: it requires an explicit human directive naming the channel, plus `--dry-run` preview and `--yes` confirmation through `slack-cli`. There is no "unsend" for team members who already read it.
|
|
3. **Respect bounded reads.** Slack paginates; never page past what the task needs. `slack-cli --limit N` caps every listing, and responses summarize records rather than dumping raw payloads.
|
|
4. **Verify webhooks before trusting them.** Any handler that accepts Slack events must verify `X-Slack-Signature` and `X-Slack-Request-Timestamp` against the app signing secret, or anyone who can reach the endpoint can forge events. `slack-cli webhook verify` does this check.
|
|
5. **Keep evidence bounded.** Quote short message excerpts and IDs; never paste full threads, tokens, or file contents into chat.
|
|
|
|
## The slack-cli script
|
|
|
|
`scripts/slack-cli` is an agent-first, stdlib-only CLI over the Slack Web API. It covers the full issue scope: messages, channels, threads, search, files, and webhook verification.
|
|
|
|
```bash
|
|
slack/scripts/slack-cli --help # no token or network needed
|
|
slack/scripts/slack-cli --json --limit 10 channels list
|
|
slack/scripts/slack-cli --json messages list --channel C12345
|
|
slack/scripts/slack-cli --json threads list --channel C12345 --ts 1712345678.000001
|
|
slack/scripts/slack-cli --json search messages --query "incident"
|
|
slack/scripts/slack-cli --json files list --limit 5
|
|
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --dry-run # preview
|
|
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --yes # confirmed
|
|
slack/scripts/slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp 1712345678
|
|
```
|
|
|
|
Exit codes: 0 success, 1 API error or failed verification, 2 usage error. Sends are guarded: without `--dry-run` or `--yes` the script refuses with exit 1 and never calls the API. Reads are bounded by `--limit` (default 20, max 100).
|
|
|
|
## Operating loop
|
|
|
|
1. **Scope the workspace surface**: which channel(s) are relevant, what the question is (what was said, who said it, when), and whether any action is a mutation.
|
|
2. **Read with bounds**: `channels list` to find IDs, `messages list`/`threads list` for history, `search messages` for cross-channel discovery. All read-only.
|
|
3. **Triage the answer**: map the question to evidence (thread replies for context, search for the exact phrase, files list for shared artifacts).
|
|
4. **Act with confirmation**: only a human directive to send, previewed with `--dry-run` and confirmed with `--yes`.
|
|
5. **Verify**: confirm the posted message `ts`/channel in the response, or for webhooks confirm the signature check result before trusting the event.
|
|
|
|
## Messages, channels, threads
|
|
|
|
- **Channels** (`conversations.list`): public and private channels, archived state, member counts. Channel IDs (`C...`) are the stable key for every other call — resolve names to IDs before use.
|
|
- **Messages** (`conversations.history`): newest-first history in a channel, one page at a time. Message records carry `ts` (the ID), `user`, and `text`. Use `--cursor` from the response metadata to page deliberately.
|
|
- **Threads** (`conversations.replies`): replies keyed by the parent `ts`; the parent message is the first result. Thread replies keep `thread_ts` set to the parent.
|
|
- **Sending** (`chat.postMessage`): the only mutation in this skill's surface. Always preview with `--dry-run`, confirm with `--yes`, and pass `--thread-ts` to reply in a thread instead of starting a new message. Verify the returned `ts` and channel.
|
|
|
|
## Search and files
|
|
|
|
- **Search** (`search.messages`): full-text search across visible history with Slack's search syntax (`from:`, `in:`, quoted phrases, `before:`/`after:`). Results include the matching channel; `total` tells you how many matches exist while `matches` stays bounded by `--limit`.
|
|
- **Files** (`files.list`): files shared in the workspace, filterable by channel or user, with permalinks and sizes. Downloading file *content* is out of scope for the CLI (bounded reads); use it to find the file, then fetch the permalink with an authenticated request when a human asks for the content.
|
|
|
|
## Webhook verification
|
|
|
|
Slack signs every HTTP request to your event/command/interactivity endpoints. To verify:
|
|
|
|
1. Take the raw request body (exactly as received — do not re-encode).
|
|
2. Check `X-Slack-Request-Timestamp` is within ~5 minutes of now (replay protection).
|
|
3. Compute `v0=HMAC_SHA256(signing_secret, "v0:" + timestamp + ":" + body)` and compare with `X-Slack-Signature` using a constant-time comparison.
|
|
4. Reject with 401 if the timestamp is stale or the signature mismatches.
|
|
|
|
`slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp <unix>` runs exactly this check against `SLACK_WEBHOOK_SECRET` (or `--secret`) and reports a constant-time-verified result. Always verify before trusting event payloads — unverified webhook endpoints accept forged events.
|
|
|
|
## Reference routing
|
|
|
|
| Load when | Reference |
|
|
|---|---|
|
|
| Sources, scope tables, refresh procedure | `references/00-source-index.md` |
|
|
| API method surface, pagination, scopes, and webhook verification details | `references/01-web-api-operations.md` |
|
|
|
|
## Included artifacts
|
|
|
|
- `scripts/slack-cli`: bounded, stdlib-only CLI (messages, channels, threads, search, files, webhook verify; `--json`; `--limit`; send gated by `--dry-run`/`--yes`).
|
|
- `tests/test_slack_cli.py`: 16 deterministic tests against a stub Slack API, including the mutation gate and the read-only contract.
|
|
- `references/`: dated source index + web API operations reference.
|
|
- `evals/evals.json`: six output-quality evaluation cases for agent runs.
|
|
|
|
## Verification boundary
|
|
|
|
| Claim | Minimum evidence |
|
|
|---|---|
|
|
| A channel exists and its name | `slack-cli channels list --json` returns it with its `C...` ID |
|
|
| A message was sent | `slack-cli messages send --yes` returns the new `ts` and channel, and `messages list` shows it |
|
|
| A search found matches | `slack-cli search messages --query "..." --json` returns `total_matches` with bounded matches |
|
|
| A webhook is authentic | `slack-cli webhook verify` exits 0 with `verified: true` for the exact body/signature/timestamp |
|
|
| A file exists | `slack-cli files list --json` returns its `F...` ID and permalink |
|
|
|
|
## Hard boundaries
|
|
|
|
- Never send a message or thread reply without a human directive, `--dry-run` preview, and `--yes` confirmation — Slack posts are public, durable, and unreadable-back.
|
|
- Never trust an inbound webhook without signature and timestamp verification.
|
|
- Never page reads past `--limit`; never dump full threads, tokens, or file contents into chat.
|
|
- This skill operates the Slack Web API. It does not build Slack apps (application development), manage users/org settings (admin console), or cover alternative channels platforms (that is their own tooling).
|
|
|
|
## When not to use
|
|
|
|
- **Building Slack apps or bots** (Block Kit, Bolt, slash-command apps, OAuth flow design) — that is application development; see [backend-engineering](../backend-engineering/SKILL.md) for service design.
|
|
- **Workspace administration** (user provisioning, deprovisioning, org-level settings, SSO/SAML, data exports at the org level) — that is the Slack admin console, not the Web API.
|
|
- **Other team-chat platforms** (Discord, Mattermost, Teams) — each has its own tooling; this skill covers Slack only.
|
|
- **Company-wide policy on messaging or channel governance** — that is organizational policy, not an API operation.
|