# Mattermost Notify

> Send Mattermost DM notifications to users about task completions, errors, or updates. Use for long-running tasks (5+ minutes), important alerts, or when user explicitly requests notification.

- Skill: `shakudo-io/mattermost-notify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shakudo-io/mattermost-notify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shakudo-io/mattermost-notify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: Shakudo-io (https://skillmd.com/u/shakudo-io)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shakudo-io/mattermost-notify

---


# Mattermost Notification Skill

This skill teaches you how to send Mattermost direct messages and notifications correctly.

## Prerequisites

- Mattermost MCP tools available (`mattermost_*`)
- Already authenticated (token set via `mattermost_set_auth_token` or `mattermost_login`)

## When to Use This Skill

- **Long-running tasks** (5+ minutes): Notify when complete
- **Task failures**: Notify with error details
- **User requests**: When user explicitly asks for notification
- **Important updates**: Status changes requiring attention

## Core Workflows

### 1. Send a DM to a Specific User

**Step-by-step:**

1. **Find the user by username**:
   ```
   mattermost_get_user_by_username({ username: "yevgeniy" })
   ```
   Returns: `{ id: "user-uuid", username: "yevgeniy", ... }`

2. **Create a direct channel with the user**:
   ```
   mattermost_create_direct_channel({ user_id: "<user-uuid>" })
   ```
   Returns: `{ id: "channel-uuid", ... }`

3. **Post the message**:
   ```
   mattermost_post_message({
     channel_id: "<channel-uuid>",
     message: "Your message here"
   })
   ```

### 2. Notify About Task Completion

**Template for success notification:**

```
mattermost_post_message({
  channel_id: "<dm-channel-id>",
  message: `**Task Completed**

**Task**: <task-name>
**Status**: Success
**Duration**: <time-taken>

**Summary**: <brief-description-of-what-was-done>

**Next steps**: <any-follow-up-actions-needed>`
})
```

### 3. Notify About Task Failure

**Template for error notification:**

```
mattermost_post_message({
  channel_id: "<dm-channel-id>",
  message: `**Task Failed**

**Task**: <task-name>
**Status**: Failed
**Error**: <error-message>

**Details**:
\`\`\`
<stack-trace-or-error-details>
\`\`\`

**Suggested fix**: <what-might-resolve-the-issue>
**Action needed**: <what-user-should-do-next>`
})
```

### 4. Reply to an Existing Thread

If there's an existing conversation thread:

```
mattermost_post_message({
  channel_id: "<channel-id>",
  message: "Your reply message",
  root_id: "<parent-post-id>"  # This makes it a threaded reply
})
```

## Message Formatting

Mattermost supports Markdown:

- **Bold**: `**text**`
- *Italic*: `*text*`
- ~~Strikethrough~~: `~~text~~`
- `Code`: `` `code` ``
- Code blocks: ` ```language\ncode\n``` `
- Links: `[text](url)`
- Lists: `- item` or `1. item`
- Headers: `# H1`, `## H2`, etc.
- Mentions: `@username`

## Common Notification Templates

### Build/Deploy Complete

```markdown
**Deployment Successful**

**Service**: my-service-name
**Environment**: production
**Version**: v1.2.3
**URL**: https://my-service.dev.hyperplane.dev

Deployment completed in 45 seconds.
```

### Long Task Progress Update

```markdown
**Progress Update**

**Task**: Data processing pipeline
**Progress**: 75% complete (750/1000 records)
**ETA**: ~5 minutes remaining

Processing continues...
```

### Error with Context

```markdown
**Error Alert**

**Service**: my-api
**Error Type**: ConnectionError
**Time**: 2026-01-19 12:30:00 UTC

**Error Message**:
\`\`\`
Failed to connect to database: connection refused
\`\`\`

**Relevant Logs**:
\`\`\`
2026-01-19 12:29:58 Attempting connection...
2026-01-19 12:30:00 Connection timeout after 30s
\`\`\`

**Suggested Actions**:
1. Check if database pod is running
2. Verify network policies allow connection
3. Check database credentials
```

## Advanced Workflows

### Send to a Channel (Not DM)

1. **Get team ID**:
   ```
   mattermost_get_teams()
   ```

2. **Find channel by name**:
   ```
   mattermost_get_channel_by_name({
     team_id: "<team-uuid>",
     channel_name: "general"
   })
   ```

3. **Post to channel**:
   ```
   mattermost_post_message({
     channel_id: "<channel-uuid>",
     message: "Message to channel"
   })
   ```

### Check for User Response

After sending a message, check if user replied:

```
mattermost_get_thread({ post_id: "<your-message-id>" })
```

Or check for specific user response:

```
mattermost_check_user_response({
  post_id: "<your-message-id>",
  user_id: "<user-uuid>"
})
```

### Add Reaction to a Post

```
mattermost_add_reaction({
  post_id: "<post-id>",
  emoji_name: "white_check_mark"  # No colons
})
```

Common emoji names: `white_check_mark`, `x`, `eyes`, `rocket`, `thumbsup`, `thumbsdown`

## Bot Management

### Creating a Bot Account

**Important**: The standard MCP token (`shakudobabyagi`) cannot create bots due to a permission restriction. You must use a token from the `yevgeniy` user.

**Step-by-step workflow:**

1. **Create a token for yevgeniy** (using the admin token):
   ```bash
   curl -X POST "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/users/ibzbp75tzbdc7r8ctnw91j7c6e/tokens" \
     -H "Authorization: Bearer hb1o5s59stgkimh4hfbbjuwyro" \
     -H "Content-Type: application/json" \
     -d '{"description": "bot-creation-token"}'
   ```
   Save the returned `token` value.

2. **Create the bot** (using yevgeniy's token):
   ```bash
   curl -X POST "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/bots" \
     -H "Authorization: Bearer <yevgeniy-token>" \
     -H "Content-Type: application/json" \
     -d '{"username": "my-new-bot", "display_name": "My New Bot", "description": "Bot purpose"}'
   ```
   Save the returned `user_id` for the bot.

3. **Create an access token for the bot**:
   ```bash
   curl -X POST "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/users/<bot-user-id>/tokens" \
     -H "Authorization: Bearer <yevgeniy-token>" \
     -H "Content-Type: application/json" \
     -d '{"description": "bot-access-token"}'
   ```
   The returned `token` is what the bot uses for authentication.

### List Existing Bots

```bash
curl -s "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/bots" \
  -H "Authorization: Bearer hb1o5s59stgkimh4hfbbjuwyro" | jq '.'
```

### Known Bots

| Username | Description | Owner |
|----------|-------------|-------|
| system-bot | System bot | yevgeniy |
| shakbot | ShakBot | yevgeniy |
| shakudo-monitor | Prometheus alerts | - |

### Why Bot Creation Requires Special Handling

The `shakudobabyagi` user has `system_admin` role with `create_bot` permission, but Mattermost still returns 403. This appears to be a token-specific or user-specific restriction. The `yevgeniy` user (owner of existing bots) can create bots successfully.

**Key user IDs:**
- `yevgeniy`: `ibzbp75tzbdc7r8ctnw91j7c6e`
- `shakudobabyagi`: `hyf6w6wd83887ctj7wzrmwk4nc`

## Best Practices

1. **Be concise**: Keep messages short and scannable
2. **Use formatting**: Bold for key info, code blocks for errors
3. **Include context**: Task name, status, and relevant details
4. **Suggest actions**: Always tell user what to do next
5. **Don't spam**: Only notify for significant events
6. **Thread replies**: Use `root_id` to keep conversations organized

## Known Users

When sending DMs to Shakudo team members:

| Name | Username | Common Use |
|------|----------|------------|
| Yevgeniy | `yevgeniy` | Primary user, long-running task notifications |

To find other users:
```
mattermost_get_teams()  # Get team ID first
mattermost_search_posts({ team_id: "<team-id>", terms: "from:username" })
```