slack-canvas

name	slack-canvas
description	Use when running from a Slack-linked sandbox and you need to read or update a Slack canvas via the `slack` CLI, especially to locate sections and insert Mighty spec hyperlinks back into the canvas.

Slack Canvas

Use this skill only when both conditions are true:

• The run is Slack-linked (MIGHTY_SLACK_CHANNEL / MIGHTY_SLACK_THREAD_TS are present).
• SLACK_BOT_TOKEN is available in the sandbox.

Safety

• Do not mutate canvases unless the user explicitly asked for a canvas update.
• Keep edits narrow: prefer replacing one section or inserting one new section at a time.
• Never print or persist SLACK_BOT_TOKEN.

Read Path

• Fetch the current Slack thread context first when you need surrounding conversation:

slack fetch --channel "$MIGHTY_SLACK_CHANNEL" --thread-ts "$MIGHTY_SLACK_THREAD_TS" --output "$MIGHTY_SLACK_CONTEXT_DIR"

• There is no public Slack API to read full canvas content. Use section lookup for targeted reads.

Section Lookup

Use slack canvas-sections to find the section you want to update. Pass raw Slack criteria JSON.

slack canvas-sections --id "F0123456789" --json '{"contains_text":"Decision log"}'

If you already know the canvas permalink, --url works too.

Supported criteria:

• section_types: ["h1"], ["h2"], ["h3"], ["any_header"]
• contains_text: text to search for within sections

Create Canvas

slack canvas-create --title "My Canvas" --content-file /tmp/initial.md

Optionally tab it into a channel:

slack canvas-create --title "Sprint Notes" --content-file /tmp/notes.md --channel-id C0123456789

Delete Canvas

slack canvas-delete --id "F0123456789"

Access Management

Set access (levels: read, write, owner):

slack canvas-access-set --id "F0123456789" --access-level write --channel-ids C0123456789
slack canvas-access-set --id "F0123456789" --access-level read --user-ids U0123456789,U9876543210

Remove access:

slack canvas-access-delete --id "F0123456789" --channel-ids C0123456789

Add Mighty Links

Hyperlinks are Markdown links inside canvas markdown content:

See [Slack Context CLI](https://mighty.example/specs/mt-spec-wjfu).

Slack canvas edits are section-level. To add a hyperlink to existing text, look up the target section ID, then replace that section with markdown containing the link.

Edit Path

For a simple single-section change, use the structured flags:

slack canvas-edit \
  --id "F0123456789" \
  --operation replace \
  --section-id "SEC123" \
  --content-file /tmp/canvas-section.md

Supported operations:

• insert_after — insert after a section (requires --section-id)
• insert_before — insert before a section (requires --section-id)
• insert_at_start — insert at the beginning of the canvas
• insert_at_end — insert at the end of the canvas
• replace — replace a section (optional --section-id; omit to replace entire canvas)
• delete — delete a section (requires --section-id)

For advanced multi-change edits, pass raw Slack changes JSON (using the Slack API document_content object format):

slack canvas-edit \
  --id "F0123456789" \
  --changes-json '[{"operation":"insert_after","section_id":"SEC123","document_content":{"type":"markdown","markdown":"[Spec](https://mighty.example/specs/mt-spec-123)"}}]'

To rename a canvas:

slack canvas-edit \
  --id "F0123456789" \
  --changes-json '[{"operation":"rename","title_content":{"type":"markdown","markdown":"New Title :white_check_mark:"}}]'

Recommended Workflow

1. Fetch the thread and inspect whether the canvas actually needs a write.
2. Use slack canvas-sections to locate the exact section to change.
3. Prepare the replacement markdown with Mighty spec links.
4. Apply a narrow slack canvas-edit.
5. Summarize exactly what section you changed and which Mighty links you inserted.