fix(slack-publish): gracefully handle missing SLACK_BOT_TOKEN with setup guidance

plugins/slack-publish/.claude-plugin/plugin.json

@@ -5,5 +5,5 @@
     "name": "1shooperman",
     "email": "contact@aglflorida.com"
   },
-  "version": "1.0.0"
+  "version": "1.0.1"
 }

plugins/slack-publish/agents/agent-token-checker.md

@@ -0,0 +1,17 @@
+---
+name: agent-token-checker
+description: Checks whether SLACK_BOT_TOKEN is available (env var or .env file). Returns exit code 0 if found, 1 if missing. Used by the publish skill before attempting to post to Slack.
+allowed-tools: [Bash]
+model: haiku
+---
+
+## Instruction
+
+Run the token checker script and report the result:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/verify_slackbot_token.py"
+```
+
+- Exit code **0** → token is available. Report: "Token found."
+- Exit code **1** → token is missing. Report: "Token missing."

plugins/slack-publish/scripts/verify_slackbot_token.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Exit 0 if SLACK_BOT_TOKEN is available, 1 otherwise."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def find_token() -> str | None:
+    token = os.environ.get("SLACK_BOT_TOKEN")
+    if token:
+        return token
+
+    cwd = Path.cwd()
+    for candidate in [cwd / ".env", cwd / ".env.local"]:
+        if not candidate.is_file():
+            continue
+        for raw in candidate.read_text(encoding="utf-8").splitlines():
+            line = raw.strip()
+            if line.startswith("SLACK_BOT_TOKEN="):
+                value = line.split("=", 1)[1].strip()
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+                    value = value[1:-1]
+                if value:
+                    return value
+    return None
+
+
+def main() -> int:
+    return 0 if find_token() else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

plugins/slack-publish/skills/publish/SKILL.md

@@ -16,29 +16,45 @@ Parse `<markdown-file>` and `<channel>` from `$ARGUMENTS`. Both are required —
 
 ## Workflow
 
-1. Verify the markdown file exists at the given path.
+1. **Check for `SLACK_BOT_TOKEN`** before anything else — use the `slack-publish:agent-token-checker` agent. If it reports "Token missing", **stop here** and show the user this guidance:
+   If this exits non-zero, **stop here** and show the user this guidance:
 
-2. Run the publisher script, quoting each argument as a discrete shell word to prevent shell injection:
+   > **`SLACK_BOT_TOKEN` is not set.** To publish to Slack you need a bot token. Here's how to get one:
+   >
+   > 1. Go to **https://api.slack.com/apps** and click **Create New App → From a manifest**
+   > 2. Select your workspace and paste the contents of `slack-app-manifest.yaml` (in the plugin directory)
+   > 3. Click **Install to Workspace** and copy the **Bot User OAuth Token** (starts with `xoxb-`)
+   > 4. Invite the bot to your target channel: `/invite @Markdown Publisher`
+   > 5. Set the token in one of these ways:
+   >    - **Shell environment**: `export SLACK_BOT_TOKEN='xoxb-...'`
+   >    - **`.env` file** in your working directory: `SLACK_BOT_TOKEN=xoxb-...`
+   >    - **Pass at runtime**: re-run with `--env-file /path/to/file.env`
+   >
+   > Once the token is set, try again.
+
+2. Verify the markdown file exists at the given path.
+
+3. Run the publisher script, quoting each argument as a discrete shell word to prevent shell injection:
    ```bash
    python3 "${CLAUDE_PLUGIN_ROOT}/skills/publish/scripts/publish_markdown_to_slack.py" \
      -- "<markdown-file>" "<channel>"
    ```
 
-3. If `SLACK_BOT_TOKEN` is not set in the environment, the script will also check `.env` and `.env.local` in the current directory automatically. To use a different token file:
+4. To use a different token file:
    ```bash
    python3 "${CLAUDE_PLUGIN_ROOT}/skills/publish/scripts/publish_markdown_to_slack.py" \
      -- "<markdown-file>" "<channel>" --env-file "<path>"
    ```
 
-4. To preview the converted Slack text without posting:
+5. To preview the converted Slack text without posting:
    ```bash
    python3 "${CLAUDE_PLUGIN_ROOT}/skills/publish/scripts/publish_markdown_to_slack.py" \
      -- "<markdown-file>" "<channel>" --dry-run
    ```
 
-5. Report success including the resolved channel ID and message timestamp (`ts`).
+6. Report success including the resolved channel ID and message timestamp (`ts`).
 
-6. If posting fails, report the exact Slack API error. Common causes:
+7. If posting fails, report the exact Slack API error. Common causes:
    - Missing token scopes (`chat:write`, `channels:read`, `groups:read`)
    - Bot not invited to the destination channel