docs: clarify file uploads via message send

README.md

@@ -72,7 +72,7 @@ agent-slack
 ├── message
 │   ├── get   <target>             # fetch 1 message (+ thread meta )
 │   ├── list  <target>             # fetch thread or recent channel messages
-│   ├── send  <target> <text>      # send / reply (supports --attach)
+│   ├── send  <target> [text]      # send / reply (supports --attach)
 │   ├── draft <target> [text]      # open Slack-like editor in browser
 │   ├── edit  <target> <text>      # edit a message
 │   ├── delete <target>            # delete a message
@@ -229,9 +229,25 @@ agent-slack message delete "#general" --workspace "myteam" --ts "1770165109.6283
 
 Attach options for `message send`:
 
-- `--attach <path>` upload a local file (repeatable)
+- `--attach <path>` upload a local file (repeatable; `<text>` is optional when attaching files)
 - `--blocks <path>` send raw [Block Kit](https://docs.slack.dev/block-kit/) blocks from a JSON file (or `-` for stdin). Bypasses the automatic markdown-to-rich-text conversion, unlocking header/divider/section/table blocks and other structured layouts. Cannot be combined with `--attach`.
 
+Upload files through `message send`:
+
+```bash
+# Upload a file without a message
+agent-slack message send "#general" --attach ./report.md
+
+# Upload with an initial comment
+agent-slack message send "#general" "Coverage report" --attach ./report.md
+
+# Upload into a thread
+agent-slack message send "https://workspace.slack.com/archives/C123/p1700000000000000" --attach ./report.md
+
+# Upload multiple files
+agent-slack message send "#general" "Reports" --attach ./report.md --attach ./data.csv
+```
+
 Example — post a message with a native Slack table block:
 
 ```bash

llms.txt

@@ -12,7 +12,7 @@
 
 - Read Slack messages, threads, and channel history from any URL or channel name
 - Search Slack messages and files with filters for channel, user, date, and content type
-- Send, edit, delete Slack messages and add/remove emoji reactions programmatically
+- Send, edit, delete Slack messages, upload local files with `message send --attach`, and add/remove emoji reactions programmatically
 - Auto-download Slack file attachments (snippets, images, files) to local paths for AI agent consumption
 - Token-efficient compact JSON output so LLMs can consume Slack data cheaply
 - Zero-config auth: auto-detects Slack Desktop credentials on macOS, Windows, and Linux — with Chrome, Brave, and Firefox fallbacks

skills/agent-slack/SKILL.md

@@ -6,7 +6,8 @@ description: |
   - Browsing recent channel messages / channel history
   - Downloading Slack attachments (snippets, images, files) to local paths
   - Searching Slack messages or files
-  - Sending, editing, or deleting a message; adding/removing reactions
+  - Sending messages, including local file uploads via `message send --attach`
+  - Editing or deleting a message; adding/removing reactions
   - Listing channels/conversations; creating channels and inviting users
   - Fetching a Slack canvas as markdown
   - Looking up Slack users
@@ -15,7 +16,7 @@ description: |
   - Discovering and running Slack workflows
   - Managing saved-for-later messages (Later tab)
   - Viewing all unread messages (inbox/unreads view)
-  Triggers: "slack message", "slack thread", "slack URL", "slack link", "read slack", "reply on slack", "search slack", "channel history", "recent messages", "channel messages", "latest messages", "mark as read", "mark read", "slack later", "saved for later", "save for later", "slack unreads", "slack inbox", "unread slack"
+  Triggers: "slack message", "slack thread", "slack URL", "slack link", "read slack", "reply on slack", "search slack", "channel history", "recent messages", "channel messages", "latest messages", "mark as read", "mark read", "slack later", "saved for later", "save for later", "slack unreads", "slack inbox", "unread slack", "upload file", "slack file upload", "send file slack"
 ---
 
 # Slack automation with `agent-slack`
@@ -160,9 +161,18 @@ agent-slack message delete "general" --workspace "myteam" --ts "1770165109.62837
 
 Attach options for `message send`:
 
-- `--attach <path>` upload a local file (repeatable)
+- `--attach <path>` upload a local file (repeatable; message text is optional when attaching files)
 - `--blocks <path>` send raw [Block Kit](https://docs.slack.dev/block-kit/) blocks from a JSON file (or `-` for stdin). Enables headers, dividers, table blocks, and other structured layouts. Incompatible with `--attach`.
 
+File upload examples:
+
+```bash
+agent-slack message send "general" --attach ./report.md
+agent-slack message send "general" "Coverage report" --attach ./report.md
+agent-slack message send "https://workspace.slack.com/archives/C123/p1700000000000000" --attach ./report.md
+agent-slack message send "general" "Reports" --attach ./report.md --attach ./data.csv
+```
+
 `message send` returns `channel_id` plus the posted `ts` and a `permalink` (for non-attachment sends). `thread_ts` appears only when replying in a thread.
 
 Mentions: just write `@U05BRPTKL6A`, `@here`, `@channel`, or `@everyone` — the CLI converts them to real Slack mention tokens and escapes literal `&`/`<`/`>` in your text. You don't need to wrap IDs yourself.

skills/agent-slack/references/commands.md

@@ -59,10 +59,16 @@ Run `agent-slack --help` (or `agent-slack <command> --help`) for the full option
     - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
     - `--thread-ts <seconds>.<micros>` (optional, channel mode only)
 
-- `agent-slack message send <target> <text>`
+- `agent-slack message send <target> [text]`
   - If `<target>` is a Slack message URL, replies in that message’s thread.
   - Otherwise posts to the channel/DM.
+  - `[text]` is optional when uploading files with `--attach`; when present, it becomes the initial comment on the first uploaded file.
   - Bullet lists (`- `, `* `, `• `, `1. `, etc.) are automatically converted to Slack’s native rich text format, so recipients see real editable bullets instead of plain-text dashes.
+  - Examples:
+    - `agent-slack message send "general" --attach ./report.md`
+    - `agent-slack message send "general" "Coverage report" --attach ./report.md`
+    - `agent-slack message send "https://workspace.slack.com/archives/C123/p1700000000000000" --attach ./report.md`
+    - `agent-slack message send "general" "Reports" --attach ./report.md --attach ./data.csv`
   - Options:
     - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
     - `--thread-ts <seconds>.<micros>` (optional, channel mode only)