From c3850b908f6a612b1e52136d4d381e6f3fd45425 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 23:18:13 +0000 Subject: [PATCH] chore: update agent skills --- .agents/skills/create-slack-app/SKILL.md | 23 +++++++++------ .agents/skills/deploy-slack-app/SKILL.md | 20 +++++++++---- .agents/skills/slack-api/SKILL.md | 20 +++++++------ .agents/skills/slack-cli/SKILL.md | 28 +++++++++++++++--- .agents/skills/slack-docs/SKILL.md | 2 +- .claude/skills/create-slack-app/SKILL.md | 23 +++++++++------ .claude/skills/deploy-slack-app/SKILL.md | 20 +++++++++---- .claude/skills/slack-api/SKILL.md | 20 +++++++------ .claude/skills/slack-cli/SKILL.md | 28 +++++++++++++++--- .claude/skills/slack-docs/SKILL.md | 2 +- skills-lock.json | 37 +++++++++++++++--------- 11 files changed, 153 insertions(+), 70 deletions(-) diff --git a/.agents/skills/create-slack-app/SKILL.md b/.agents/skills/create-slack-app/SKILL.md index 7b28854..7790853 100644 --- a/.agents/skills/create-slack-app/SKILL.md +++ b/.agents/skills/create-slack-app/SKILL.md @@ -81,13 +81,13 @@ SLACK_CMD sandbox list --team **If the developer has no Developer Program account**, `sandbox list` returns nothing useful, because sandboxes belong to the developer program account whose email matches the authenticated user rather than to the workspace. If they say they do have an account, check that the email they are logged in with matches it before sending them to sign up, and log into a workspace under that email if not. Point them at , and offer the Free Team path in 3b as a way to start building now rather than waiting on signup. - **If a sandbox exists**: Show it and confirm they want to use it. -- **If no sandbox exists**: Create one. Ask the developer for a name and a password with AskUserQuestion, then run: +- **If no sandbox exists**: Create one. Ask the developer for a name with AskUserQuestion, then run: ```bash - SLACK_CMD sandbox create --team --name --password + SLACK_CMD sandbox create --team --name ``` - **Important**: the password is a credential. Do NOT echo it, restate it, or write it into a summary. Pass it straight to the command, the same rule Step 4c applies to API keys. + Do not pass `--password`, and do not ask the developer for a password. Without it, the developer signs into the sandbox with a link sent to their email, so no credential passes through this conversation or the command line. This needs Slack CLI v4.11.0 or later. Check the version from Step 1b before running it, and if it is older, ask the developer to run `SLACK_CMD upgrade` first. An older CLI prompts for a password, which fails when run from the agent. If the developer wants password sign-in, have them create the sandbox in the browser and set the password there. Sandboxes can also be created in the browser at . @@ -215,7 +215,7 @@ Confirm the project was created successfully by checking that the directory exis ### 4c. Set required environment variables (agent templates only) -If the developer chose an agent template (Starter Agent or Support Agent), they need to set the required API key for their chosen AI provider. Ask for the key value using AskUserQuestion, then set it using the Slack CLI from within the project directory. +If the developer chose an agent template (Starter Agent or Support Agent), they need to set the required API key for their chosen AI provider. The key is a credential, so the developer types it into the Slack CLI's own prompt, which hides what they type. Never ask for a key with AskUserQuestion or in chat, and never put a key value in a command. **Required environment variables by provider:** @@ -225,19 +225,23 @@ If the developer chose an agent template (Starter Agent or Support Agent), they | `openai-agents-sdk` | `OPENAI_API_KEY` | OpenAI API key | | `pydantic-ai` | `OPENAI_API_KEY` | OpenAI API key (required). Optionally also `ANTHROPIC_API_KEY` if using Anthropic as the backend — if both are set, Anthropic is used by default. | -Use AskUserQuestion to ask the developer for their API key value(s). Then set each one: +For each variable, give the developer these two commands to run in a terminal of their own. Use the project's full path, because a new terminal may not start in the folder this session is in. Keep them as two commands: Windows PowerShell 5.1 does not accept `&&`. ```bash -cd && SLACK_CMD env set +cd +SLACK_CMD env set ``` For example: ```bash -cd my-slack-agent && SLACK_CMD env set ANTHROPIC_API_KEY sk-ant-... +cd ~/projects/my-slack-agent +SLACK_CMD env set ANTHROPIC_API_KEY ``` -**Important**: Do NOT store or echo API key values in logs or output. Only pass them directly to `SLACK_CMD env set`. +With no value given, the CLI asks for one with hidden input and saves it to the project's `.env` file. Wait for the developer to confirm each variable is set before continuing. Do not read `.env` to check it: that would load the key into the conversation. + +**Important**: Do not run this command yourself. It needs an interactive terminal, so from the agent it fails and suggests the `--value` flag. Do not retry with `--value`: that puts the key on the command line and in the conversation. If the developer pastes a key into the chat anyway, do not pass it to a command or repeat it. Ask them to run the commands above instead, and suggest rotating the key with their provider, since it is now in the conversation transcript. --- @@ -269,6 +273,7 @@ After the app is running, suggest next steps: - `SLACK_CMD` is a placeholder — always substitute the actual command name resolved in Step 1a (typically `slack`, but may be an alias). - This skill focuses on **Bolt for JavaScript** and **Bolt for Python** only. Do not suggest Deno, workflow apps, or `slack deploy` (hosted deployment). - This skill scaffolds and runs the app. It does not own Block Kit JSON. If the developer asks to build or edit a message, modal, or Home tab layout (now or in Step 6), use the `block-kit` skill instead of writing the blocks here from memory. -- `SLACK_CMD sandbox create` prompts for a name and password only when those flags are missing. Supply `--team`, `--name`, and `--password` and it runs non-interactively, so you can run it yourself rather than handing it to the developer. `SLACK_CMD sandbox list` needs `--team` for the same reason: without it the CLI prompts for which authentication to use. +- `SLACK_CMD sandbox create` prompts for a name only when `--name` is missing. Supply `--team` and `--name` and it runs non-interactively, so you can run it yourself rather than handing it to the developer. Leave out `--password`: since Slack CLI v4.11.0 the sandbox then uses email sign-in, and no password passes through the agent. `SLACK_CMD sandbox list` needs `--team` for the same reason: without it the CLI prompts for which authentication to use. +- `SLACK_CMD env set ` with no value prompts for it with hidden input. Use it for every API key, and because it needs an interactive terminal, the developer runs it rather than the agent. - Free Teams and developer sandboxes both support everything this skill builds. The CLI's `free_team_not_allowed` error is scoped to low-code workflow and function apps, which this skill does not create. - If the developer hits issues, suggest `SLACK_CMD doctor` to diagnose their setup. diff --git a/.agents/skills/deploy-slack-app/SKILL.md b/.agents/skills/deploy-slack-app/SKILL.md index d1d1ad1..9e6148d 100644 --- a/.agents/skills/deploy-slack-app/SKILL.md +++ b/.agents/skills/deploy-slack-app/SKILL.md @@ -1,6 +1,6 @@ --- name: deploy-slack-app -description: Use when a developer wants to deploy, host, or run a Slack app somewhere it keeps working after the local process stops, or mentions Railway, Heroku, `railway up`, `git push heroku`, `slack deploy`, a `deploy` hook in `.slack/hooks.json`, hosting a Socket Mode or Request URL (HTTP) Bolt app, deploying from Windows, graduating an app out of a developer sandbox, or tearing down a deployed app. +description: Use when a developer wants to deploy, host, or run a Slack app somewhere it keeps working after the local process stops, or mentions Railway, Heroku, `railway up`, `git push heroku`, `slack deploy`, a `deploy` hook in `.slack/hooks.json`, hosting a Socket Mode or Request URL (HTTP) Bolt app, deploying from Windows, graduating an app out of a developer sandbox, or tearing down a deployed app. Not for conceptual questions about how Slack app hosting works, which the `slack-docs` skill answers. --- # Deploy Slack App @@ -119,21 +119,31 @@ For Heroku, the value is `./.slack/deploy-heroku.sh`. **Leave the `get-hooks` en Run `SLACK_CMD deploy` from the project root and watch the output. The CLI creates the deployed app, installs it, and then runs the hook script, so the first part of the output is app installation and the second is the provider's build. -Four flags matter when running this outside an interactive terminal, which includes most agent sessions. The CLI asks four questions, and each one is fatal unanswered: a non-interactive shell gets `The input device is not a TTY or does not support interactivity` and nothing is deployed. +Three flags matter when running this outside an interactive terminal, which includes most agent sessions. The CLI asks these questions, and each one is fatal unanswered: a non-interactive shell gets `The input device is not a TTY or does not support interactivity` and nothing is deployed. - `--skip-update` stops the CLI pausing to offer an upgrade. - `--team ` picks the workspace or organization. Use the team the developer chose in **Step 2b: Choose a Team**. - `--app deployed` selects the deployed app environment, and creates that app on a first deploy. Without it the CLI asks the developer to choose between an existing app and a new one. This is the flag most easily missed, because the prompt it answers only appears on a project that has never been deployed. -- `--org-workspace-grant all` answers the workspace-grant prompt for an org-installed app. -So the full command is `SLACK_CMD deploy --skip-update --team --app deployed --org-workspace-grant all`. +So the full command is `SLACK_CMD deploy --skip-update --team --app deployed`. Put any provider variables settled in **Step 4a: Prepare the Provider** in front of it. The hook inherits the CLI's environment, so this is how they reach the script: ```sh -HEROKU_TEAM= HEROKU_APP_NAME= SLACK_CMD deploy --skip-update --team --app deployed --org-workspace-grant all +HEROKU_TEAM= HEROKU_APP_NAME= SLACK_CMD deploy --skip-update --team --app deployed ``` +**On an Enterprise organization, ask the developer which workspaces to grant.** The first deploy to an organization stops on one more question, and the error prints it: + +```text +› Choose a workspace to grant access: + All of them + Acme Sales T0123456789 + Acme Support T0987654321 +``` + +Ask the developer the same question, with the choices in the same order: all of the organization's workspaces first, then each workspace by name. Never choose for the developer. Granting all workspaces makes the app available to everyone in the organization. Then run the deploy again with `--org-workspace-grant all` for all of them, or `--org-workspace-grant ` for one workspace. If the CLI stops without listing the workspaces, ask whether to grant all workspaces or just one, and for that workspace's team ID if they pick one. + **The deployed app is a different app from the one `SLACK_CMD run` uses.** The CLI writes the deployed app to `.slack/apps.json` and the local development app to `.slack/apps.dev.json`, keyed by team. Both keep working independently, which is the intended design, not a mistake to correct. **Commit `.slack/apps.json` after the first deploy.** It holds app and team IDs, not secrets, and the project's `.slack/.gitignore` leaves it tracked on purpose. Committing it keeps every later deploy pointed at the same app. On Heroku it also stops the deploy script warning about uncommitted changes on each re-deploy. diff --git a/.agents/skills/slack-api/SKILL.md b/.agents/skills/slack-api/SKILL.md index 32eafbf..18b9cca 100644 --- a/.agents/skills/slack-api/SKILL.md +++ b/.agents/skills/slack-api/SKILL.md @@ -118,6 +118,8 @@ Use the `slack-cli` skill — **Step 5: Authentication (`slack auth`)** — to c You do not need the CLI to call a method. Get a token of the type you determined above from the app's **OAuth & Permissions** page in the Slack app config (`https://api.slack.com/apps` → your app → **OAuth & Permissions** → **OAuth Tokens**): the **Bot User OAuth Token** (`xoxb-…`) or the **User OAuth Token** (`xoxp-…`). That page also lists the scopes currently granted — confirm the ones from Step 2 are present. Then send that token with curl or an SDK in Step 4 ("Via raw HTTP" / "Via an SDK"). +The token is a credential. Never ask the developer to paste it into the conversation, and never put it in a command. Ask them to make it available as an environment variable instead: `SLACK_BOT_TOKEN` for a bot token or `SLACK_USER_TOKEN` for a user token, either exported in their shell before they start this session or added to the project's `.env` file. Don't print or read the value: the commands in Step 4 read it from the environment. + --- ## Step 4: Call the Method (Manage) @@ -132,21 +134,21 @@ The CLI uses the developer's authenticated session, so it is the simplest path o ### Via raw HTTP (curl) -Use the **Bash tool** when the developer wants a raw request or isn't using the CLI. Send the token in the `Authorization` header — the bot or user token from Step 3 (Path B, or the CLI session). +Use the **Bash tool** when the developer wants a raw request or isn't using the CLI. Send the token from Step 3 (Path B) in the `Authorization` header. Pipe the header into curl with `-H @-` so the token stays out of the command line and the conversation: `printf` is a shell builtin, so the expanded token never appears in the process list. If the token is in the project's `.env` file, read just that line in the same command first, rather than sourcing the file, which runs it as shell code: `SLACK_BOT_TOKEN="$(sed -n 's/^SLACK_BOT_TOKEN=//p' .env | tr -d "\"'")" &&`. When the variable is not set, the `${SLACK_BOT_TOKEN:?…}` form prints `SLACK_BOT_TOKEN is not set` before Slack's `not_authed`, so the developer knows to set the variable rather than check the token. For a user token, use `$SLACK_USER_TOKEN` in place of `$SLACK_BOT_TOKEN`. **Form-encoded** (the default for most methods): ```bash -curl -s -X POST 'https://slack.com/api/conversations.list' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/conversations.list' \ + -H @- \ -d 'types=public_channel&limit=200' ``` **JSON body** (for methods taking complex arguments like `blocks`, `view`, `attachments`, `metadata`): ```bash -curl -s -X POST 'https://slack.com/api/chat.postMessage' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/chat.postMessage' \ + -H @- \ -H 'Content-Type: application/json' \ -d '{"channel":"C0123456789","text":"Hello from the API"}' ``` @@ -175,13 +177,13 @@ Methods that return collections use **cursor pagination**, not page numbers. A m ```bash # First page -curl -s -X POST 'https://slack.com/api/conversations.history' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/conversations.history' \ + -H @- \ -d 'channel=C0123456789&limit=200' # Next page — pass the cursor from response_metadata.next_cursor -curl -s -X POST 'https://slack.com/api/conversations.history' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/conversations.history' \ + -H @- \ -d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI=' ``` diff --git a/.agents/skills/slack-cli/SKILL.md b/.agents/skills/slack-cli/SKILL.md index 47d857f..9034b02 100644 --- a/.agents/skills/slack-cli/SKILL.md +++ b/.agents/skills/slack-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: slack-cli -description: "Use when a developer works with the Slack CLI (slack command) to create, run, or manage a Slack app from the terminal: logging in or authenticating (slack login), adding a team or switching workspaces, running locally (slack run), deploying, editing the app manifest, calling Web API methods (slack api), or searching Slack docs (slack docs search)." +description: "Use when a developer works with the Slack CLI (slack command) to create, run, or manage a Slack app from the terminal: logging in or authenticating (slack login), adding a team or switching workspaces, running locally (slack run), including starting an existing app to try a code change, deploying, editing the app manifest, calling Web API methods (slack api), or searching Slack docs (slack docs search)." --- # Slack CLI @@ -214,16 +214,36 @@ Run this command as a **background process** so the developer can continue worki **If an app ID was found:** ```bash -cd && SLACK_CMD run --org-workspace-grant=all --app= +cd && SLACK_CMD run --app= ``` **If no apps — use the team ID:** ```bash -cd && SLACK_CMD run --org-workspace-grant=all --team= +cd && SLACK_CMD run --team= ``` -Tell the developer the app is running in the background. They can ask: +### Ask before granting workspaces on an Enterprise organization + +The first time an app is installed to an Enterprise organization, the CLI asks which of the organization's workspaces the app can access. A background process cannot answer, so the CLI stops with `The input device is not a TTY or does not support interactivity` and prints the prompt it would have shown: + +```text +› Choose a workspace to grant access: + All of them + Acme Sales T0123456789 + Acme Support T0987654321 +``` + +When you see this, **ask the developer the same question, with the choices in the same order**: all of the organization's workspaces first, then each workspace by name. Never choose for the developer. Granting all workspaces makes the app available to everyone in the organization, so it is the developer's decision. Then run the command again with their answer: + +- **All of them**: add `--org-workspace-grant=all` +- **One workspace**: add `--org-workspace-grant=`, using the `T` team ID printed next to that workspace + +If the CLI stops without listing the workspaces, ask the developer whether to grant all workspaces or just one, and for that workspace's team ID if they pick one. + +### Confirm the app is running + +Read the background process's output before saying anything to the developer. The workspace question above only shows up there, and the process has already exited when it does. Once the output shows the app has started, tell the developer the app is running in the background. They can ask: - "What's the status of the dev server?" — to check on it - "Show me the output from slack run" — to see activity logs diff --git a/.agents/skills/slack-docs/SKILL.md b/.agents/skills/slack-docs/SKILL.md index 2b79ecb..45bf576 100644 --- a/.agents/skills/slack-docs/SKILL.md +++ b/.agents/skills/slack-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: slack-docs -description: "Use when answering a conceptual or how-to question about Slack platform features, or when asked to look up, fetch, or summarize a docs.slack.dev page, including a pasted docs.slack.dev link. Covers finding and reading official Slack docs as clean markdown." +description: "Use when answering a conceptual or how-to question about Slack platform features, or when asked to look up, fetch, or summarize a docs.slack.dev page, including a pasted docs.slack.dev link. Web API method reference pages (docs.slack.dev/reference/methods/...) belong to the `slack-api` skill. Covers finding and reading official Slack docs as clean markdown." argument-hint: "[topic or docs.slack.dev URL]" --- diff --git a/.claude/skills/create-slack-app/SKILL.md b/.claude/skills/create-slack-app/SKILL.md index 7b28854..7790853 100644 --- a/.claude/skills/create-slack-app/SKILL.md +++ b/.claude/skills/create-slack-app/SKILL.md @@ -81,13 +81,13 @@ SLACK_CMD sandbox list --team **If the developer has no Developer Program account**, `sandbox list` returns nothing useful, because sandboxes belong to the developer program account whose email matches the authenticated user rather than to the workspace. If they say they do have an account, check that the email they are logged in with matches it before sending them to sign up, and log into a workspace under that email if not. Point them at , and offer the Free Team path in 3b as a way to start building now rather than waiting on signup. - **If a sandbox exists**: Show it and confirm they want to use it. -- **If no sandbox exists**: Create one. Ask the developer for a name and a password with AskUserQuestion, then run: +- **If no sandbox exists**: Create one. Ask the developer for a name with AskUserQuestion, then run: ```bash - SLACK_CMD sandbox create --team --name --password + SLACK_CMD sandbox create --team --name ``` - **Important**: the password is a credential. Do NOT echo it, restate it, or write it into a summary. Pass it straight to the command, the same rule Step 4c applies to API keys. + Do not pass `--password`, and do not ask the developer for a password. Without it, the developer signs into the sandbox with a link sent to their email, so no credential passes through this conversation or the command line. This needs Slack CLI v4.11.0 or later. Check the version from Step 1b before running it, and if it is older, ask the developer to run `SLACK_CMD upgrade` first. An older CLI prompts for a password, which fails when run from the agent. If the developer wants password sign-in, have them create the sandbox in the browser and set the password there. Sandboxes can also be created in the browser at . @@ -215,7 +215,7 @@ Confirm the project was created successfully by checking that the directory exis ### 4c. Set required environment variables (agent templates only) -If the developer chose an agent template (Starter Agent or Support Agent), they need to set the required API key for their chosen AI provider. Ask for the key value using AskUserQuestion, then set it using the Slack CLI from within the project directory. +If the developer chose an agent template (Starter Agent or Support Agent), they need to set the required API key for their chosen AI provider. The key is a credential, so the developer types it into the Slack CLI's own prompt, which hides what they type. Never ask for a key with AskUserQuestion or in chat, and never put a key value in a command. **Required environment variables by provider:** @@ -225,19 +225,23 @@ If the developer chose an agent template (Starter Agent or Support Agent), they | `openai-agents-sdk` | `OPENAI_API_KEY` | OpenAI API key | | `pydantic-ai` | `OPENAI_API_KEY` | OpenAI API key (required). Optionally also `ANTHROPIC_API_KEY` if using Anthropic as the backend — if both are set, Anthropic is used by default. | -Use AskUserQuestion to ask the developer for their API key value(s). Then set each one: +For each variable, give the developer these two commands to run in a terminal of their own. Use the project's full path, because a new terminal may not start in the folder this session is in. Keep them as two commands: Windows PowerShell 5.1 does not accept `&&`. ```bash -cd && SLACK_CMD env set +cd +SLACK_CMD env set ``` For example: ```bash -cd my-slack-agent && SLACK_CMD env set ANTHROPIC_API_KEY sk-ant-... +cd ~/projects/my-slack-agent +SLACK_CMD env set ANTHROPIC_API_KEY ``` -**Important**: Do NOT store or echo API key values in logs or output. Only pass them directly to `SLACK_CMD env set`. +With no value given, the CLI asks for one with hidden input and saves it to the project's `.env` file. Wait for the developer to confirm each variable is set before continuing. Do not read `.env` to check it: that would load the key into the conversation. + +**Important**: Do not run this command yourself. It needs an interactive terminal, so from the agent it fails and suggests the `--value` flag. Do not retry with `--value`: that puts the key on the command line and in the conversation. If the developer pastes a key into the chat anyway, do not pass it to a command or repeat it. Ask them to run the commands above instead, and suggest rotating the key with their provider, since it is now in the conversation transcript. --- @@ -269,6 +273,7 @@ After the app is running, suggest next steps: - `SLACK_CMD` is a placeholder — always substitute the actual command name resolved in Step 1a (typically `slack`, but may be an alias). - This skill focuses on **Bolt for JavaScript** and **Bolt for Python** only. Do not suggest Deno, workflow apps, or `slack deploy` (hosted deployment). - This skill scaffolds and runs the app. It does not own Block Kit JSON. If the developer asks to build or edit a message, modal, or Home tab layout (now or in Step 6), use the `block-kit` skill instead of writing the blocks here from memory. -- `SLACK_CMD sandbox create` prompts for a name and password only when those flags are missing. Supply `--team`, `--name`, and `--password` and it runs non-interactively, so you can run it yourself rather than handing it to the developer. `SLACK_CMD sandbox list` needs `--team` for the same reason: without it the CLI prompts for which authentication to use. +- `SLACK_CMD sandbox create` prompts for a name only when `--name` is missing. Supply `--team` and `--name` and it runs non-interactively, so you can run it yourself rather than handing it to the developer. Leave out `--password`: since Slack CLI v4.11.0 the sandbox then uses email sign-in, and no password passes through the agent. `SLACK_CMD sandbox list` needs `--team` for the same reason: without it the CLI prompts for which authentication to use. +- `SLACK_CMD env set ` with no value prompts for it with hidden input. Use it for every API key, and because it needs an interactive terminal, the developer runs it rather than the agent. - Free Teams and developer sandboxes both support everything this skill builds. The CLI's `free_team_not_allowed` error is scoped to low-code workflow and function apps, which this skill does not create. - If the developer hits issues, suggest `SLACK_CMD doctor` to diagnose their setup. diff --git a/.claude/skills/deploy-slack-app/SKILL.md b/.claude/skills/deploy-slack-app/SKILL.md index d1d1ad1..9e6148d 100644 --- a/.claude/skills/deploy-slack-app/SKILL.md +++ b/.claude/skills/deploy-slack-app/SKILL.md @@ -1,6 +1,6 @@ --- name: deploy-slack-app -description: Use when a developer wants to deploy, host, or run a Slack app somewhere it keeps working after the local process stops, or mentions Railway, Heroku, `railway up`, `git push heroku`, `slack deploy`, a `deploy` hook in `.slack/hooks.json`, hosting a Socket Mode or Request URL (HTTP) Bolt app, deploying from Windows, graduating an app out of a developer sandbox, or tearing down a deployed app. +description: Use when a developer wants to deploy, host, or run a Slack app somewhere it keeps working after the local process stops, or mentions Railway, Heroku, `railway up`, `git push heroku`, `slack deploy`, a `deploy` hook in `.slack/hooks.json`, hosting a Socket Mode or Request URL (HTTP) Bolt app, deploying from Windows, graduating an app out of a developer sandbox, or tearing down a deployed app. Not for conceptual questions about how Slack app hosting works, which the `slack-docs` skill answers. --- # Deploy Slack App @@ -119,21 +119,31 @@ For Heroku, the value is `./.slack/deploy-heroku.sh`. **Leave the `get-hooks` en Run `SLACK_CMD deploy` from the project root and watch the output. The CLI creates the deployed app, installs it, and then runs the hook script, so the first part of the output is app installation and the second is the provider's build. -Four flags matter when running this outside an interactive terminal, which includes most agent sessions. The CLI asks four questions, and each one is fatal unanswered: a non-interactive shell gets `The input device is not a TTY or does not support interactivity` and nothing is deployed. +Three flags matter when running this outside an interactive terminal, which includes most agent sessions. The CLI asks these questions, and each one is fatal unanswered: a non-interactive shell gets `The input device is not a TTY or does not support interactivity` and nothing is deployed. - `--skip-update` stops the CLI pausing to offer an upgrade. - `--team ` picks the workspace or organization. Use the team the developer chose in **Step 2b: Choose a Team**. - `--app deployed` selects the deployed app environment, and creates that app on a first deploy. Without it the CLI asks the developer to choose between an existing app and a new one. This is the flag most easily missed, because the prompt it answers only appears on a project that has never been deployed. -- `--org-workspace-grant all` answers the workspace-grant prompt for an org-installed app. -So the full command is `SLACK_CMD deploy --skip-update --team --app deployed --org-workspace-grant all`. +So the full command is `SLACK_CMD deploy --skip-update --team --app deployed`. Put any provider variables settled in **Step 4a: Prepare the Provider** in front of it. The hook inherits the CLI's environment, so this is how they reach the script: ```sh -HEROKU_TEAM= HEROKU_APP_NAME= SLACK_CMD deploy --skip-update --team --app deployed --org-workspace-grant all +HEROKU_TEAM= HEROKU_APP_NAME= SLACK_CMD deploy --skip-update --team --app deployed ``` +**On an Enterprise organization, ask the developer which workspaces to grant.** The first deploy to an organization stops on one more question, and the error prints it: + +```text +› Choose a workspace to grant access: + All of them + Acme Sales T0123456789 + Acme Support T0987654321 +``` + +Ask the developer the same question, with the choices in the same order: all of the organization's workspaces first, then each workspace by name. Never choose for the developer. Granting all workspaces makes the app available to everyone in the organization. Then run the deploy again with `--org-workspace-grant all` for all of them, or `--org-workspace-grant ` for one workspace. If the CLI stops without listing the workspaces, ask whether to grant all workspaces or just one, and for that workspace's team ID if they pick one. + **The deployed app is a different app from the one `SLACK_CMD run` uses.** The CLI writes the deployed app to `.slack/apps.json` and the local development app to `.slack/apps.dev.json`, keyed by team. Both keep working independently, which is the intended design, not a mistake to correct. **Commit `.slack/apps.json` after the first deploy.** It holds app and team IDs, not secrets, and the project's `.slack/.gitignore` leaves it tracked on purpose. Committing it keeps every later deploy pointed at the same app. On Heroku it also stops the deploy script warning about uncommitted changes on each re-deploy. diff --git a/.claude/skills/slack-api/SKILL.md b/.claude/skills/slack-api/SKILL.md index 32eafbf..18b9cca 100644 --- a/.claude/skills/slack-api/SKILL.md +++ b/.claude/skills/slack-api/SKILL.md @@ -118,6 +118,8 @@ Use the `slack-cli` skill — **Step 5: Authentication (`slack auth`)** — to c You do not need the CLI to call a method. Get a token of the type you determined above from the app's **OAuth & Permissions** page in the Slack app config (`https://api.slack.com/apps` → your app → **OAuth & Permissions** → **OAuth Tokens**): the **Bot User OAuth Token** (`xoxb-…`) or the **User OAuth Token** (`xoxp-…`). That page also lists the scopes currently granted — confirm the ones from Step 2 are present. Then send that token with curl or an SDK in Step 4 ("Via raw HTTP" / "Via an SDK"). +The token is a credential. Never ask the developer to paste it into the conversation, and never put it in a command. Ask them to make it available as an environment variable instead: `SLACK_BOT_TOKEN` for a bot token or `SLACK_USER_TOKEN` for a user token, either exported in their shell before they start this session or added to the project's `.env` file. Don't print or read the value: the commands in Step 4 read it from the environment. + --- ## Step 4: Call the Method (Manage) @@ -132,21 +134,21 @@ The CLI uses the developer's authenticated session, so it is the simplest path o ### Via raw HTTP (curl) -Use the **Bash tool** when the developer wants a raw request or isn't using the CLI. Send the token in the `Authorization` header — the bot or user token from Step 3 (Path B, or the CLI session). +Use the **Bash tool** when the developer wants a raw request or isn't using the CLI. Send the token from Step 3 (Path B) in the `Authorization` header. Pipe the header into curl with `-H @-` so the token stays out of the command line and the conversation: `printf` is a shell builtin, so the expanded token never appears in the process list. If the token is in the project's `.env` file, read just that line in the same command first, rather than sourcing the file, which runs it as shell code: `SLACK_BOT_TOKEN="$(sed -n 's/^SLACK_BOT_TOKEN=//p' .env | tr -d "\"'")" &&`. When the variable is not set, the `${SLACK_BOT_TOKEN:?…}` form prints `SLACK_BOT_TOKEN is not set` before Slack's `not_authed`, so the developer knows to set the variable rather than check the token. For a user token, use `$SLACK_USER_TOKEN` in place of `$SLACK_BOT_TOKEN`. **Form-encoded** (the default for most methods): ```bash -curl -s -X POST 'https://slack.com/api/conversations.list' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/conversations.list' \ + -H @- \ -d 'types=public_channel&limit=200' ``` **JSON body** (for methods taking complex arguments like `blocks`, `view`, `attachments`, `metadata`): ```bash -curl -s -X POST 'https://slack.com/api/chat.postMessage' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/chat.postMessage' \ + -H @- \ -H 'Content-Type: application/json' \ -d '{"channel":"C0123456789","text":"Hello from the API"}' ``` @@ -175,13 +177,13 @@ Methods that return collections use **cursor pagination**, not page numbers. A m ```bash # First page -curl -s -X POST 'https://slack.com/api/conversations.history' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/conversations.history' \ + -H @- \ -d 'channel=C0123456789&limit=200' # Next page — pass the cursor from response_metadata.next_cursor -curl -s -X POST 'https://slack.com/api/conversations.history' \ - -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \ +printf 'Authorization: Bearer %s\n' "${SLACK_BOT_TOKEN:?SLACK_BOT_TOKEN is not set}" | curl -s -X POST 'https://slack.com/api/conversations.history' \ + -H @- \ -d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI=' ``` diff --git a/.claude/skills/slack-cli/SKILL.md b/.claude/skills/slack-cli/SKILL.md index 47d857f..9034b02 100644 --- a/.claude/skills/slack-cli/SKILL.md +++ b/.claude/skills/slack-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: slack-cli -description: "Use when a developer works with the Slack CLI (slack command) to create, run, or manage a Slack app from the terminal: logging in or authenticating (slack login), adding a team or switching workspaces, running locally (slack run), deploying, editing the app manifest, calling Web API methods (slack api), or searching Slack docs (slack docs search)." +description: "Use when a developer works with the Slack CLI (slack command) to create, run, or manage a Slack app from the terminal: logging in or authenticating (slack login), adding a team or switching workspaces, running locally (slack run), including starting an existing app to try a code change, deploying, editing the app manifest, calling Web API methods (slack api), or searching Slack docs (slack docs search)." --- # Slack CLI @@ -214,16 +214,36 @@ Run this command as a **background process** so the developer can continue worki **If an app ID was found:** ```bash -cd && SLACK_CMD run --org-workspace-grant=all --app= +cd && SLACK_CMD run --app= ``` **If no apps — use the team ID:** ```bash -cd && SLACK_CMD run --org-workspace-grant=all --team= +cd && SLACK_CMD run --team= ``` -Tell the developer the app is running in the background. They can ask: +### Ask before granting workspaces on an Enterprise organization + +The first time an app is installed to an Enterprise organization, the CLI asks which of the organization's workspaces the app can access. A background process cannot answer, so the CLI stops with `The input device is not a TTY or does not support interactivity` and prints the prompt it would have shown: + +```text +› Choose a workspace to grant access: + All of them + Acme Sales T0123456789 + Acme Support T0987654321 +``` + +When you see this, **ask the developer the same question, with the choices in the same order**: all of the organization's workspaces first, then each workspace by name. Never choose for the developer. Granting all workspaces makes the app available to everyone in the organization, so it is the developer's decision. Then run the command again with their answer: + +- **All of them**: add `--org-workspace-grant=all` +- **One workspace**: add `--org-workspace-grant=`, using the `T` team ID printed next to that workspace + +If the CLI stops without listing the workspaces, ask the developer whether to grant all workspaces or just one, and for that workspace's team ID if they pick one. + +### Confirm the app is running + +Read the background process's output before saying anything to the developer. The workspace question above only shows up there, and the process has already exited when it does. Once the output shows the app has started, tell the developer the app is running in the background. They can ask: - "What's the status of the dev server?" — to check on it - "Show me the output from slack run" — to see activity logs diff --git a/.claude/skills/slack-docs/SKILL.md b/.claude/skills/slack-docs/SKILL.md index 2b79ecb..45bf576 100644 --- a/.claude/skills/slack-docs/SKILL.md +++ b/.claude/skills/slack-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: slack-docs -description: "Use when answering a conceptual or how-to question about Slack platform features, or when asked to look up, fetch, or summarize a docs.slack.dev page, including a pasted docs.slack.dev link. Covers finding and reading official Slack docs as clean markdown." +description: "Use when answering a conceptual or how-to question about Slack platform features, or when asked to look up, fetch, or summarize a docs.slack.dev page, including a pasted docs.slack.dev link. Web API method reference pages (docs.slack.dev/reference/methods/...) belong to the `slack-api` skill. Covers finding and reading official Slack docs as clean markdown." argument-hint: "[topic or docs.slack.dev URL]" --- diff --git a/skills-lock.json b/skills-lock.json index d84d138..6d0ca19 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -6,63 +6,72 @@ "sourceType": "github", "skillPath": "skills/block-kit/SKILL.md", "computedHash": "04748a453ee9ad97263e82effb17f8ce6788cccc19375b386fc8023ba6708493", - "installMode": "copy" + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "create-slack-app": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/create-slack-app/SKILL.md", - "computedHash": "4a0c9055a219fe49614d990c74a0e4c1c3fbc8c4d005c6adbbdd91f106c6fe02", - "installMode": "copy" + "computedHash": "34723cf63b151456471eac7bc46d0859dd9e968b4193b15ba3cb42e562d69aca", + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "deploy-slack-app": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/deploy-slack-app/SKILL.md", - "computedHash": "b45a2154bf461795d0cbab3d4c66fafc1293edfe0c0b54ad51a0e5f1f4e37e2a", - "installMode": "copy" + "computedHash": "f228a11e02336bd1c5a1e0d04d3bf64e21c9c64ec868424f81aa0e132ecab1ba", + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "slack-api": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/slack-api/SKILL.md", - "computedHash": "e452e766b936e2a93ebe5fd2ec33ff3f1c68c6d6d4b64fd1eae1d4fb2ccc21f6", - "installMode": "copy" + "computedHash": "da79f0eee8d7af9c8247f1530328e794015a7b42e73fce2c82ee7fcd300b1a09", + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "slack-cli": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/slack-cli/SKILL.md", - "computedHash": "4506040f94cbe20252b26cc8463c8eec4b89899ae6e4e46a4137b7e6b91d0b20", - "installMode": "copy" + "computedHash": "bfa0d297a23cf0206366e241c69a0fd4240efa8bb34a1ff129b94fadee0d1a24", + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "slack-docs": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/slack-docs/SKILL.md", - "computedHash": "07013bbbb0ffa8bf0f62ca3a8fb8c0762f970c2058c3a00544068cebfc4fee2f", - "installMode": "copy" + "computedHash": "4c506e7b2fd40b268c8e2fcdf02bc072f33e4b32421cab7a1842b030d9ebacb3", + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "slack-messaging": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/slack-messaging/SKILL.md", "computedHash": "4bb55059cf58a4614d896a0e8ad3421d8d5d0ceb76bc1fec6153914cae41934c", - "installMode": "copy" + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "slack-search": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/slack-search/SKILL.md", "computedHash": "e3fe85c29469e157db02e0898b14c1532f9e35cbe239a814388c7cd2c1a24746", - "installMode": "copy" + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" }, "test-slack-app": { "source": "slackapi/slack-skills-plugin", "sourceType": "github", "skillPath": "skills/test-slack-app/SKILL.md", "computedHash": "818e70481f7671d2cbc3e103631d626e4b29bc7520ffbfcfeffc6f920467850d", - "installMode": "copy" + "installMode": "copy", + "commit": "a6db580e584b44d723dda4f6c6657aa0d04bf4c1" } } }