stablyai · nwparker · Jul 18, 2026 · Jul 18, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,4 +2,8 @@
 
 ## Skills
 
-This repo includes an installable skill at `skills/agent-slack/SKILL.md`. Ensure this stay in sync w/ the code (and Readme.md)
+This repo includes an installable skill at `skills/agent-slack/SKILL.md`. Keep it aligned with the code and README.
+
+- Write the skill for an agent executing Slack tasks, not as user-facing documentation.
+- Keep it token-efficient: do not add tables of contents, exhaustive command/flag catalogs, or duplicate the README and CLI help.
+- Treat the installed `agent-slack --help` and subcommand help as authoritative. Keep only non-obvious workflow, safety, targeting, and output behavior in the skill.
diff --git a/README.md b/README.md
@@ -108,7 +108,7 @@ agent-slack
 
 Notes:
 
-- Output is **always JSON** and aggressively pruned (`null`/empty fields removed).
+- Slack data commands output aggressively pruned JSON (`null`/empty fields removed); help, update, and some authentication setup commands output text.
 - Attached files are auto-downloaded and returned as absolute local paths.
 
 ## Authentication (no fancy setup)
@@ -220,6 +220,8 @@ agent-slack message draft "https://workspace.slack.com/archives/C123/p1700000000
 
 After sending, the editor shows a "View in Slack" link to the posted message.
 
+`message draft` is send-capable. In CI, it skips the browser editor and immediately sends supplied text; do not use it for a compose-only request in a noninteractive environment.
+
 ### Reply, edit, delete, and react
 
 ```bash
@@ -384,7 +386,7 @@ When to use which:
 
 ### Files (snippets/images/attachments)
 
-`message get/list` auto-download attached files to an agent-friendly temp directory and return file metadata in `message.files[]`, including `name` when Slack provides the original filename and `path` for the local download. Failed downloads keep the attachment entry, preserve `message.files[].path` with a local `.download-error.txt` file, and include `message.files[].error`. `search messages` and `search all` use the same attachment shape for message results, while `search files` skips entries whose download fails.
+`message get/list` auto-download attached files to an agent-friendly temp directory and return file metadata in `message.files[]`, including `name` when Slack provides the original filename and `path` for the local download. Failed downloads keep the attachment entry, preserve `message.files[].path` with a local `.download-error.txt` file, and include `message.files[].error`. `search messages` and `search all` use the same attachment shape for message results, while `search files` skips entries whose download fails. Use `search messages --content-type file` when you also need the source-message permalink for a reply.
 
 - macOS default: `~/.agent-slack/tmp/downloads/`
 
@@ -421,6 +423,9 @@ agent-slack user list --workspace "https://workspace.slack.com" --limit 200 | jq
 # Get one user by id or handle
 agent-slack user get U12345678 --workspace "https://workspace.slack.com" | jq .
 agent-slack user get "@alice" --workspace "https://workspace.slack.com" | jq .
+
+# Open a DM or group DM with one to eight other users (the caller is implicit)
+agent-slack user dm-open "@alice" "@bob" --workspace "https://workspace.slack.com" | jq .
 ```
 
 ### Unreads (inbox view)
@@ -498,6 +503,8 @@ agent-slack later remind "https://workspace.slack.com/archives/C123/p17000000000
 agent-slack later remind "https://workspace.slack.com/archives/C123/p1700000000000000" --in tomorrow
 ```
 
+Named reminder days such as `tomorrow` and `monday` mean 9:00 in the CLI process's local timezone. Use a Unix timestamp when timezone precision matters.
+
 ### Create or fetch a Canvas as Markdown
 
 ```bash

diff --git a/llms.txt b/llms.txt
@@ -6,7 +6,7 @@
 
 - [README](https://github.com/stablyai/agent-slack/blob/main/README.md): Full documentation with installation, authentication, and usage examples
 - [Agent Skill (SKILL.md)](https://github.com/stablyai/agent-slack/blob/main/skills/agent-slack/SKILL.md): Integration guide for Claude Code, Cursor, Codex, and custom AI agents
-- [Command References](https://github.com/stablyai/agent-slack/blob/main/skills/agent-slack/references/): Detailed per-command documentation with examples
+- [Agent References](https://github.com/stablyai/agent-slack/blob/main/skills/agent-slack/references/): Non-obvious targeting, output, and download behavior
 
 ## Key Features
 

diff --git a/skills/agent-slack/SKILL.md b/skills/agent-slack/SKILL.md
@@ -5,50 +5,38 @@ description: "Slack CLI for agents: read URLs/threads/history/unreads/later/canv
 
 # agent-slack
 
-CLI on `$PATH`: `agent-slack ...`. If missing, prefer:
+Use `agent-slack` from `$PATH`. If it is missing, install it with:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/main/install.sh | sh
 ```
 
 Fallback: `npm i -g agent-slack` (Node >= 22.5).
 
-Treat the installed CLI's `agent-slack --help` and `agent-slack <command> --help` output as authoritative for supported commands and flags.
+Run `agent-slack --help` or the relevant subcommand help before guessing a command or flag.
+If a capability named here is absent from installed help, report version skew instead of guessing. Do not self-update the CLI without explicit authorization.
 
-Safety: read/search freely. Treat sends, edits, deletes, reactions, invitations, channel or canvas creation, mark-read operations, schedules, uploads, scheduled-message cancellation, and `workflow run` as write actions; perform them only when explicitly requested. Workflow runs can execute downstream actions. Prefer `message draft`.
+## Safety
 
-Auth: `agent-slack auth whoami`; if needed `auth import-desktop`, `auth import-brave`, `auth import-chrome`, or `auth import-firefox`, then `auth test`.
+- Read and search freely.
+- Perform write actions only when explicitly requested: sends, edits, deletes, reactions, invitations, channel or canvas creation, mark-read operations, scheduling or canceling delivery, uploads, Later state/reminder changes, DM/group-DM creation, and `workflow run`. Workflow runs can execute downstream actions.
+- For compose- or review-only requests, return proposed text without invoking Slack. `message draft` is send-capable; use it only when the user explicitly asks to open the interactive editor. In CI or another noninteractive environment, do not invoke it without separate authorization to send immediately: CI skips the editor and sends supplied text.
 
-For labeled links inside bullet or numbered lists, use Slack's `<URL|label>` syntax. Auto-converted lists do not convert CommonMark `[label](URL)` links into labeled link elements.
+## Workflow
 
-Common commands:
+1. Run `agent-slack auth whoami`. If needed, import credentials with `auth import-desktop`, `auth import-brave`, `auth import-chrome`, or `auth import-firefox`, then run `auth test`.
+2. Prefer a Slack message URL when one is available. It carries the workspace, channel, and timestamp needed by most message operations.
+3. Choose the narrowest read operation: `message get` for one message, `message list` for a full thread or channel history, and `search messages` or `search files` for discovery.
+4. Use output limits such as `--limit`, `--max-body-chars`, and `--max-content-chars` to avoid unnecessary context.
+5. For a requested write, execute only the requested mutation and verify the resulting JSON metadata.
 
-```bash
-agent-slack message get "SLACK_URL"
-agent-slack message list "SLACK_URL"
-agent-slack message list "general" --limit 20
-agent-slack search messages "query" --channel "general"
-agent-slack message draft "general" "text"
-agent-slack message send "URL_OR_CHANNEL" "text" --attach ./file.md
-agent-slack message send "general" "text" --schedule-in "3h"
-agent-slack message scheduled list
-agent-slack message scheduled cancel "SCHEDULED_ID" --channel "CHANNEL_ID"
-agent-slack unreads
-agent-slack later list
-agent-slack canvas create --file ./plan.md --title "Plan"
-agent-slack canvas create --markdown $'# Plan\n\n- [ ] Ship it'
-agent-slack canvas get "CANVAS_URL"
-agent-slack workflow list "general"
-agent-slack user list
-agent-slack channel list
-agent-slack user dm-open @alice @bob
-```
+For scheduled writes, prefer `--schedule` with an ISO 8601 timestamp and explicit offset when timezone matters. Named `--schedule-in` phrases use the executing environment's local timezone; confirm that it matches the user's intent.
+
+Named `later remind --in` values such as `tomorrow` or `monday` also use the executing environment's local timezone at 9:00. Confirm that timezone or pass an explicit Unix timestamp.
 
-With multiple workspaces, pass `--workspace "team"` or set `SLACK_WORKSPACE_URL`. Attachments include local `path` in JSON.
-Treat Slack user IDs beginning with `U` or `W` equivalently.
+Ordinary `message send` and `message edit` calls auto-convert lists. `message send --blocks` uses supplied blocks, while `message send --attach` sends its initial comment without automatic list conversion. Inside auto-converted lists, use Slack's `<URL|label>` syntax because CommonMark `[label](URL)` links are not converted into labeled link elements.
 
-For non-trivial usage, read the bundled references:
+## Conditional references
 
-- [references/commands.md](references/commands.md): command map and flags
-- [references/targets.md](references/targets.md): URL, channel, and direct-message targeting rules
-- [references/output.md](references/output.md): JSON shapes and download paths
+- Read [references/targets.md](references/targets.md) only when choosing between a message URL, channel, or user target, or when resolving multiple workspaces.
+- Read [references/output.md](references/output.md) only when handling returned message or canvas metadata, resolved users, or downloaded and failed attachments.