Discourse.b8-skill.md | Learn how to use Discourse Forum

---
name: discourse.b8-skill.md
version: 1.0.0
description: Standalone guide for understanding and navigating a Discourse forum, including categories, topics, posts, tags, topic lists, search, filters, notifications, messages, chat, internal Discourse AI agents, and the boundary between forum features and external agent integrations.
homepage: https://www.discourse.org/
metadata:
  b8:
    canonical_name: discourse.b8-skill.md
    category: forum-navigation
    platform: Discourse
    access_model: public-read where exposed; account- and permission-scoped participation
    internal_ai: Discourse AI Bot agents configured by the forum
    external_ai: Discourse MCP or runtime-specific plugins
    write_access: false
    updated: 2026-07-14
---

# discourse.b8-skill.md

Use this skill to understand or navigate a Discourse forum.

It describes the forum surface itself. It does not require a specific community structure, theme, plugin set, AI provider, external agent runtime, or administrator configuration.

## Scope

Use for:

- understanding how Discourse organizes information;
- choosing between categories, tags, topic lists, search, and filters;
- reading and participating in topics;
- finding account activity, messages, chat, bookmarks, and notifications;
- understanding internal Discourse AI Bot agents;
- distinguishing ordinary forum use from external-agent integration;

Do not use this skill as:

- a Discourse installation guide;
- an administrator configuration manual;
- a plugin, theme, or core-development guide;
- an API endpoint catalogue;
- authorization to create accounts, post, moderate, or change forum data;
- evidence that a feature is enabled on a particular forum.

## Source authority

Use sources in this order:

1. the current forum interface and its visible permissions;
2. the forum's own rules, FAQ, terms, privacy policy, and `/llms-full.txt` when available;
3. current official Discourse documentation;
4. the current official Discourse documentation for platform behavior;
5. the original documentation for an external connector when external integration is the actual task.

Research material may inform this skill, but it is not part of the navigation output.

## Mental model

```text
Discourse site
├── Categories
│   ├── Subcategories
│   └── Topics
│       ├── Original post
│       └── Replies
├── Tags
│   └── Cross-category topic labels
├── Topic lists
│   ├── Latest
│   ├── New
│   ├── Unread
│   └── Top
├── Search and topic filters
├── Users and groups
├── Private messages
├── Chat, when enabled
└── AI Bot, when Discourse AI is enabled and configured
```

A category gives a topic its primary location. Tags describe the topic across category boundaries.

A topic is a titled conversation. The first post defines the subject. Replies follow within that topic.

## Core terms

| Term | Meaning |
| --- | --- |
| Site | One Discourse forum with its own configuration, rules, categories, groups, permissions, theme, and plugins |
| Category | Primary container for topics; may define permissions, templates, and notification defaults |
| Subcategory | Category nested beneath another category |
| Topic | Titled conversation containing an original post and replies |
| Post | One message inside a topic |
| Original post / OP | First post, which establishes the topic's subject |
| Reply | Post responding to the topic or another post |
| Tag | Cross-category label applied to a topic |
| Topic list | Ordered collection of topics such as Latest, New, Unread, Top, a category, or a tag |
| User | Registered identity used for participation and account-specific state |
| Group | Collection of users used for access, mentions, roles, or administration |
| Trust level | Site-configurable participation level based on forum rules and activity |
| Private message / PM | Durable private topic visible only to its participants and permitted staff |
| Chat | Faster conversation surface, available only when enabled |
| Bookmark | Saved post or topic, optionally with a reminder |
| Notification | Account signal for replies, mentions, messages, likes, watched content, chat, or staff actions |
| Topic map | Summary area showing participants, reply count, links, dates, and related topic information |
| Timeline | Vertical topic control for moving through long conversations |
| AI Bot | Internal Discourse AI conversation surface |
| AI Agent | Site-configured AI Bot behavior, instructions, model access, knowledge, tools, and group availability |
| MCP | External protocol connector used by a separate AI client to access Discourse capabilities |

## Surface variations

A Discourse site's visible interface may change because of:

- desktop versus mobile layout;
- theme and theme components;
- enabled plugins;
- site settings;
- login state;
- trust level;
- group membership;
- category permissions;
- moderator or administrator status.

Do not conclude that a feature is absent merely because its control is not in the expected location. Check the sidebar, header, user menu, topic controls, and site documentation.

## Standard route patterns

These are common Discourse routes. A site may change its homepage or hide routes according to configuration and permissions.

| Route | Purpose |
| --- | --- |
| `/` | Site homepage |
| `/categories` | Category overview |
| `/latest` | Topics ordered by recent activity |
| `/new` | Topics considered new for the current user |
| `/unread` | Tracked or previously read topics with unread activity |
| `/top` | High-activity topics for a selected period |
| `/tags` | Tag index |
| `/tag/<tag>` | Topics carrying one tag |
| `/c/<category-slug>/<id>` | Category topic list |
| `/t/<topic-slug>/<id>` | Topic |
| `/u/<username>` | User profile and activity surface, subject to visibility |
| `/g/<group>` | Group page, subject to visibility |
| `/search` | Full-text search |
| `/filter` | Structured topic-list filter |
| `/about` | Site information |
| `/faq` | Site guidelines or FAQ |
| `/llms-full.txt` | Optional machine-readable public forum context for agents and language models |

Prefer links already exposed by the site instead of constructing URLs from memory.

## Choosing the correct surface

| Goal | Start with |
| --- | --- |
| Understand the site's main areas | Categories |
| See what changed recently | Latest |
| Find topics not previously opened | New |
| Resume tracked conversations with new replies | Unread |
| Find sustained or high-activity discussions | Top |
| Follow one subject across categories | Tags |
| Find words, phrases, users, dates, or statuses | Search |
| Build a reusable topic list from several conditions | Filter |
| Find your own activity | Avatar menu or user profile |
| Resume a private durable conversation | Messages |
| Hold rapid conversation | Chat, when enabled |
| Ask a configured in-forum AI assistant | AI Bot, when enabled |
| Connect an outside AI client | MCP or a runtime-specific plugin |

`New` and `Unread` are personalized. Their contents depend on account state, tracking behavior, and site settings.

## Navigation procedure

When asked to locate information on a Discourse site:

1. Identify the site and the user's access state.
2. Check the site's visible navigation and rules.
3. Classify the request:
   - broad site area;
   - recent activity;
   - personalized updates;
   - known subject;
   - exact phrase or author;
   - structured criteria;
   - private conversation;
   - internal AI interaction;
   - external integration.
4. Select the narrowest suitable surface.
5. Inspect the topic's category, tags, original post, dates, topic map, and status.
6. Read enough replies to determine whether the answer changed over time.
7. Follow links to:
   - continued topics;
   - merged or split discussions;
   - updated documentation;
   - canonical announcements;
   - accepted solutions, when the solved feature is enabled.
8. Return the direct route and explain why it is the correct destination.

Do not answer from a topic title or search snippet alone when the current answer depends on later replies.

## Browsing topic lists

### Categories

Use Categories when the user does not yet know where a subject belongs.

A category can define:

- subject boundary;
- access permissions;
- required or restricted tags;
- new-topic templates;
- notification defaults;
- moderator ownership;
- subcategories.

Read the category description or pinned "About" topic before posting.

### Latest

Use Latest to inspect recent activity across visible categories.

Latest reflects the most recently active topics, not necessarily newly created topics.

### New

Use New for topics that Discourse considers new to the logged-in user.

The exact definition can be adjusted by site and user preferences. Do not describe New as a universal fixed time window.

### Unread

Use Unread for topics with unread posts that the user is tracking or otherwise follows according to their account state.

Unread is not a global list of all recently updated topics.

### Top

Use Top for topics ranked by activity over a selectable period.

Top is useful for finding established or high-signal discussions, but ranking does not prove correctness or current validity.

### Tags

Use tags when one subject spans several categories.

A topic can carry multiple tags. A tag does not replace the topic's primary category.

## Reading a topic

Inspect:

1. title;
2. category and subcategory;
3. tags;
4. original post;
5. author and publication date;
6. edit history, when available;
7. topic status such as pinned, closed, archived, solved, or wiki;
8. topic map;
9. timeline;
10. later corrections, staff notices, and linked continuations.

Discourse normally reopens a topic near the user's last-read position. Use the timeline to move to the first post, last post, or another point in a long discussion.

Treat an edited original post as potentially more current than early replies, but verify whether the edit history or later posts change its meaning.

## Participation

### Before posting

1. Search for the subject.
2. Read the category description and pinned guidance.
3. Check whether an existing topic already covers the same issue.
4. Confirm that the topic is current and not superseded.
5. Select the narrowest correct category.
6. Add only tags that describe the topic.
7. Use a specific title that states the actual subject.

### Reply versus new topic

Reply to an existing topic when:

- the subject is the same;
- the reply advances that conversation;
- the existing topic remains current;
- the category is appropriate.

Create a new topic when:

- the subject is materially different;
- the old topic is closed, obsolete, or too broad;
- the reply would redirect the original conversation;
- the category requires a separate report or proposal.

Link related topics instead of duplicating their full contents.

### Composer behavior

Depending on configuration, the composer may support:

- Markdown-like formatting;
- quotes;
- mentions;
- links and oneboxes;
- uploads;
- emoji;
- polls;
- category templates;
- tags;
- preview;
- saved drafts.

Drafts are generally saved automatically for the logged-in user. Do not assume an unsent draft is public.

### Post actions

Common post actions include:

| Action | Use |
| --- | --- |
| Reply | Continue the topic or respond to a specific post |
| Quote | Preserve the exact context being answered |
| Like | Lightweight positive acknowledgment |
| Link / share | Obtain a stable link to the post or topic |
| Bookmark | Save for later or attach a reminder |
| Edit | Correct or improve one's own post when permitted |
| Flag | Privately alert moderators to a problem |
| Delete | Remove one's post when permitted and consistent with site rules |

Use flags for moderation concerns rather than starting a public accusation about another user.

### Mentions

- `@username` notifies a user when permitted.
- `@group` may notify a group when the group is mentionable.
- Avoid unnecessary mass mentions.
- A mention does not grant access to a private category or message.

## Private messages and chat

### Private messages

Private messages are topic-like, durable conversations restricted to participants and any administrators or systems authorized by the site's policy and configuration.

Use them for:

- account-specific matters;
- sensitive coordination;
- invitations;
- private support;
- conversations that should not be public.

Do not assume a private message is invisible to all administrators or covered by end-to-end encryption.

### Chat

Chat is a faster conversation surface available only when the site enables it.

Use chat for:

- rapid coordination;
- short questions;
- active event conversation;
- lightweight social interaction.

Use topics or messages when information must remain searchable, durable, structured, or easy to reference later.

## Search

Start with plain words or a quoted phrase. Add operators only when the result set is too broad.

### High-value search operators

| Syntax | Meaning |
| --- | --- |
| `"exact phrase"` | Search for a phrase |
| `in:title` | Search topic titles |
| `in:first` | Search original posts |
| `in:replies` | Search replies |
| `in:personal` | Search private messages visible to the user |
| `in:bookmarks` | Search bookmarked content |
| `in:created` | Search topics created by the user |
| `in:posted` | Search topics in which the user posted |
| `@username` or `user:username` | Search by author |
| `category:name` or `categories:name` | Restrict by category |
| `tag:name` or `tags:name` | Restrict by tag |
| `before:YYYY-MM-DD` | Posts before a date |
| `after:YYYY-MM-DD` | Posts on or after a date |
| `status:open` | Topics not closed or archived |
| `status:closed` | Closed topics |
| `status:archived` | Archived topics |
| `status:noreplies` | Topics with no replies |
| `order:latest` | Newest matching posts first |
| `order:oldest` | Oldest matching posts first |
| `order:views` | Highest-view matching topics first |
| `order:likes` | Most-liked matching posts first |

Operators can be combined:

```text
category:support tag:authentication after:2026-01-01 order:latest
```

Search results remain permission-scoped. An operator cannot expose content the user is not allowed to see.

## Topic filters

Use `/filter` when the desired result is a topic list rather than matching individual posts.

Filter syntax uses:

```text
filter-name:value
```

Examples:

```text
category:support status:open
tag:bug created-after:30
category:development tag:plugin,theme activity-after:7
-category:off-topic -tag:solved
```

Important distinction:

```text
Search
→ retrieves matching posts and topics from text and metadata

Filter
→ builds a topic list from structured topic properties
```

The filter interface may offer autocomplete for supported filters and values. Prefer its suggestions over memorized syntax.

## Notifications

Notifications are account-specific.

Common notification sources include:

- direct replies;
- mentions;
- quoted posts;
- likes;
- private messages;
- watched topics, categories, or tags;
- bookmark reminders;
- chat;
- review-queue activity for authorized staff.

The avatar or notification menu is the primary place to inspect unseen activity.

### Topic notification levels

| Level | Typical behavior |
| --- | --- |
| Watching | Notify for every new reply |
| Tracking | Show unread counts and notify for direct interaction |
| Normal | Notify mainly for direct replies and mentions |
| Muted | Suppress ordinary notifications and visibility in some lists |

Categories and tags may also support `Watching First Post`, which notifies the user when a new topic is created.

Exact labels and defaults can vary by version and site configuration.

## Trust, groups, and permissions

Discourse commonly uses trust levels from New through Leader, but thresholds and capabilities are configurable.

Permissions may depend on:

- login state;
- trust level;
- group membership;
- category security;
- staff role;
- plugin-specific rules;
- account status.

Do not infer that a user can create topics, reply, upload, invite, message, chat, mention groups, or access AI merely because the control exists for another account.

When an action is unavailable, check:

1. category permissions;
2. trust level;
3. group membership;
4. account status;
5. site documentation;
6. whether the topic is closed or archived;
7. whether the feature is enabled.

## Internal Discourse AI Bot agents

Internal AI Bot agents are part of Discourse AI when the site enables and configures them.

A configured agent can define:

- behavioral instructions;
- model access;
- available tools;
- knowledge sources;
- forum-search capability;
- allowed user groups;
- interaction settings.

Users may encounter AI Bot through a robot control, private-message surface, or another site-defined entry point. They may be able to choose among configured agents.

Potential tools can include forum search, web research, GitHub research, settings assistance, SQL assistance, image generation, or artifact creation. Availability depends entirely on the site's configuration.

### Internal-agent boundary

```text
Internal Discourse AI agent
= configured and executed inside the Discourse AI system

External MCP client or harness plugin
= separate program connecting to Discourse from outside the forum
```

Internal AI agents do not require the user to install MCP.

An AI agent definition is not itself an autonomous external user account. A site may represent AI Bot interactions through bot users, but behavior and tool access are configured within Discourse AI.

Do not assume:

- every Discourse forum has AI Bot;
- every user can access every agent;
- every agent has the same tools;
- an internal agent can perform write or moderation actions;
- AI output is authoritative.

## External-agent integration

External integrations are not part of ordinary forum navigation.

Use this section only when a separate AI application, coding agent, desktop client, or runtime must connect to a Discourse site.

### Official Discourse MCP

The official Discourse MCP is a standalone external connector. It translates Discourse REST API capabilities into MCP tools for compatible clients.

It is appropriate for:

- external AI assistants;
- coding agents;
- local model clients;
- structured forum retrieval;
- actions supported by the installed MCP version, API key scope, account permissions, and site policy.

It is not required for:

- reading a forum in a browser;
- using normal Discourse search;
- using an internal Discourse AI Bot agent.

Installation documented by Discourse:

```bash
npm install -g @discourse/mcp@latest
```

Capabilities can change by version. Inspect the current package and documentation rather than relying on a static tool list.

### Runtime-specific plugins

A runtime plugin may expose Discourse operations directly in one agent host.

Treat each plugin as specific to:

- its runtime;
- its package version;
- its configured site;
- its authentication method;
- its declared read and write tools.

Do not treat a runtime plugin as a universal Discourse standard.

### BITwiki runtime integration

BITwiki maintains `agent.b8-plugin` for supported external runtimes connecting to BIThub:

```text
https://github.com/bitwikiorg/agent.b8-plugin
```

The repository separates runtime-native implementations for Hermes, Agent Zero, ElizaOS, and OpenClaw. This is an external integration layer. It does not configure internal Discourse AI Bot agents.

## Automated-access rules

Before an external agent retrieves or changes forum data:

1. read the site's `/llms-full.txt`, when available;
2. read its terms, FAQ, robots policy, and API rules;
3. determine whether the requested operation is public read, authenticated read, or write;
4. use an API key or user authorization with the minimum required scope;
5. obey category and account permissions;
6. respect rate limits and `Retry-After`;
7. fetch only what is needed;
8. require explicit operator intent before writing;
9. identify AI-generated content when the site or workflow requires it;
10. preserve direct source links.

`/llms-full.txt` is a machine-readable public-context surface. It is not authentication and does not grant capabilities.

## Routing responses

When answering a navigation request, return:

```text
Destination: <direct route>
Purpose: <one sentence>
Access: <only when login, group, trust, or staff permissions matter>
```

Do not return the entire site map when one route answers the request.

Examples:

```text
Destination: /categories
Purpose: Browse the forum's primary subject areas before choosing a topic list.
```

```text
Destination: /unread
Purpose: Resume tracked conversations that contain posts you have not read.
Access: Requires a logged-in account with existing tracking state.
```

```text
Destination: /filter
Purpose: Build a topic list from category, tag, status, date, or activity conditions.
```

```text
Destination: the site's AI Bot entry point
Purpose: Interact with an internal agent configured by the forum.
Access: Availability, agent choice, models, and tools depend on site configuration and group permissions.
```

## Failure handling

When a control or route is missing:

1. check whether the user is logged in;
2. check the sidebar and its `More` section;
3. inspect the avatar or user menu;
4. check the category description and site FAQ;
5. confirm that the feature is enabled;
6. check account and group permissions;
7. use `/search` or `/filter`;
8. avoid inventing a replacement route.

When documentation and the visible forum disagree, prefer the current forum behavior for that site and report the difference.