Mastodon Scout

Read-only Mastodon skill. Outputs human-readable timeline summaries or raw JSON.

Security Scan

The skill is internally consistent with its stated read-only Mastodon purpose — it only fetches timeline/search data via the Mastodon API and requires a read-only token — aside from minor metadata mismatches about declared environment variables.

Purpose & Capability

The code and SKILL.md implement a read-only Mastodon client that fetches timelines, mentions, user posts, and search results — this matches the name and description. However, the registry metadata lists no required environment variables while the SKILL.md (and the script) require MASTODON_TOKEN (required) and optionally MASTODON_INSTANCE. That metadata mismatch should be corrected but does not indicate malicious behavior.

Instruction Scope

SKILL.md limits runtime actions to invoking the bundled Python script and (optionally) helping the user create a read-only token. The instructions do not request reading unrelated files, scanning the host, or sending data to unexpected endpoints. The script only contacts the Mastodon instance provided by the user or the default instance.

Install Mechanism

No install spec; the skill is instruction-only with a bundled Python script that uses the Python standard library. Nothing is downloaded or written to disk beyond the existing script, so install risk is low.

Credentials

The script requires a single OAuth bearer token (MASTODON_TOKEN) and optionally uses MASTODON_INSTANCE and an environment LIMIT fallback. These are proportionate to a Mastodon read-only client. Small issues: registry metadata omitted these env vars while SKILL.md declares them (and metadata inside SKILL.md also lists them). Also LIMIT is read from env but not declared in the registry metadata. These are metadata inconsistencies rather than overbroad credential requests.

Persistence & Privilege

The skill does not request persistent/always-on inclusion (always: false), does not modify other skills or system config, and does not write credentials to disk. It behaves as a normal user-invoked skill.

Assessment

This skill appears to do exactly what it claims: a read-only Mastodon timeline/search helper implemented in a small Python script. Before installing: (1) confirm the registry metadata is updated to declare MASTODON_TOKEN (and optionally MASTODON_INSTANCE/LIMIT) so you know what will be required; (2) create a Mastodon application token with only the read scope (the SKILL.md explicitly recommends this) and keep the token secret — do not paste it into public logs or version control; (3) verify the Mastodon instance URL you provide is correct (the script will call whatever instance you pass); and (4) if you allow autonomous invocation of skills, remember this one can run with your token when invoked, so avoid granting it overly broad tokens. If you want extra assurance, inspect the included scripts/mastodon_scout.py locally before running it — it uses only stdlib network calls and only performs GET requests to standard Mastodon API endpoints.

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)

python3 ./scripts/mastodon_scout.py <command> [options]

Commands

Command	What it fetches
home	Authenticated user's home timeline
user-tweets	Authenticated user's own posts
mentions	Mentions of the authenticated user
search <query>	Posts matching the query

Options

--instance <url>   Mastodon instance base URL (default: $MASTODON_INSTANCE or https://mastodon.social)
--limit <int>      Number of items to return (default: $LIMIT or 20)
--json             Output raw JSON instead of human-readable text

Environment Variables

MASTODON_TOKEN      Required. OAuth bearer token.
MASTODON_INSTANCE   Optional. Instance base URL (default: https://mastodon.social).

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)

The script formats each post as:

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

The agent MAY add a brief summary after the list.

JSON Mode (--json)

Returns raw Mastodon API JSON. Return it verbatim — no interpretation.

---

Error Handling

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

Condition	Message
Token missing	Error: MASTODON_TOKEN is not set
401	Mastodon API error: 401 Unauthorized — check MASTODON_TOKEN
403	Mastodon API error: 403 Forbidden
422	Mastodon API error: 422 Unprocessable Entity
429	Mastodon API error: 429 Rate Limited — try again later

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

---

Examples That Trigger This Skill

• mastodon-scout home
• show my mastodon timeline
• check mastodon mentions
• search mastodon for "golang"
• get my mastodon posts

---

Notes

• This skill is read-only (no posting, following, or other mutations)
• scripts/mastodon_scout.py 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: https://[instance-domain]/settings/applications

Step 2: Create Application

• Click "New Application"
  • Application name: mastodon-scout (or any name)
  • Redirect URI: urn:ietf:wg:oauth:2.0:oob
  • Scopes: CRITICAL — only select read (uncheck write, follow, push)

Step 3: Get Access Token

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

Step 4: Set Environment Variable

export MASTODON_TOKEN="paste_token_here"

Step 5: Verify

python3 ./scripts/mastodon_scout.py home --limit 5

Common Mastodon Instances:

• mastodon.social — General purpose (default)
• fosstodon.org — FOSS/tech community
• mas.to — Tech focused
• hachyderm.io — 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