Mastodon Scout

Purpose

Read-only Mastodon skill. Fetches data from the Mastodon API via a bundled Python script (scripts/mastodon_scout.py). Returns human-readable summaries by default, or raw JSON with --json.

Invocation Rules (MANDATORY)

CODEBLOCK0

Commands

Options

Environment Variables

Examples

python3 ./scripts/mastodon_scout.py home
python3 ./scripts/mastodon_scout.py mentions --limit 10
python3 ./scripts/mastodon_scout.py search "golang"
python3 ./scripts/mastodon_scout.py home --json
python3 ./scripts/mastodon_scout.py home --instance https://fosstodon.org

Output Modes

Text Mode (Default)

[N] Display Name (@user@instance) · <timestamp>
<content>
↩ <replies>  🔁 <reblogs>  ⭐ <favourites>
<url>

JSON Mode (--json)

Error Handling

The script prints a human-readable error to stderr and exits non-zero:

Do not retry on error. Guide the user to Authentication Setup if the token is missing or invalid.

Examples That Trigger This Skill

• - INLINECODE12
• INLINECODE13
• INLINECODE14
• INLINECODE15
• INLINECODE16

Notes

• - This skill is read-only (no posting, following, or other mutations)
• INLINECODE17 uses stdlib only — no pip install required
• In JSON mode: output verbatim, no interpretation

Authentication Setup (Agent MAY Help)

EXCEPTION TO STRICT MODE: If the user needs help obtaining a token, the agent may provide guidance before executing the skill.

How to Obtain a Token:

Step 1: Access Development Settings

• - Log into your Mastodon instance (e.g., mastodon.social, fosstodon.org)
• Navigate to: Settings → Development (or Preferences → Development)
• Direct URL: INLINECODE18

Step 2: Create Application

• - Click "New Application"

Step 3: Get Access Token

• - Click Submit, then open the created application
• Copy the "Your access token" value

Step 4: Set Environment Variable
CODEBLOCK5

Step 5: Verify
CODEBLOCK6

Common Mastodon Instances:

• - mastodon.social — General purpose (default)
• INLINECODE23 — FOSS/tech community
• INLINECODE24 — Tech focused
• INLINECODE25 — Tech/infosec community

Security Notes:

• - Token is read-only (cannot post, follow, or delete)
• Keep token secret (don't commit to git)
• Can be revoked anytime in Development settings
• Each Mastodon instance requires its own token