Introduction
# Mastodon Scout
## Purpose
Read-only Mastodon CLI that fetches data from the Mastodon API. Returns human-readable summaries by default, or raw JSON with `--json` flag.
---
## Invocation Rules (MANDATORY)
### Binary Selection - **macOS / Darwin** → `{baseDir}/bin/mastodon-scout` - **Linux** → `{baseDir}/bin/mastodon-scout`
### Commands
#### Home Timeline ``` {baseDir}/bin/mastodon-scout home ``` Fetches the authenticated user's home timeline.
#### User Tweets ``` {baseDir}/bin/mastodon-scout user-tweets ``` Fetches the authenticated user's own posts.
#### Mentions ``` {baseDir}/bin/mastodon-scout mentions ``` Fetches mentions of the authenticated user.
#### Search ``` {baseDir}/bin/mastodon-scout search <query> ``` Searches for posts matching the query.
### Flags (Optional) ``` --instance <url> # Mastodon instance URL (default: https://mastodon.social) --limit <int> # Number of items to return (default: 20) --timeout <int> # Timeout in seconds (default: 30) --json # Output raw JSON instead of human-readable text ```
### Environment Variables (REQUIRED) ``` MASTODON_TOKEN # OAuth bearer token for authentication ```
---
## Output Modes
### Text Mode (Default) ```bash mastodon-scout home ``` Returns human-readable summary of timeline data.
The agent MAY summarize and explain the timeline results to make them more accessible to the user.
### JSON Mode ```bash mastodon-scout --json home ``` Returns raw JSON data from the Mastodon API.
When JSON mode is used, return the output verbatim without interpretation.
---
## Error Handling
- If the binary exits non-zero: - In JSON mode: return error output verbatim - In text mode: the agent MAY explain the error to the user - Do not retry
- If MASTODON_TOKEN is not set: - The binary will exit with an error message - Agent should guide the user to the authentication setup section
---
## Examples That Trigger This Skill
- `mastodon-scout home` - `show my mastodon timeline` - `check mastodon mentions` - `search mastodon for "golang"` - `get my mastodon posts`
---
## Performance Requirements
- Execute binary directly - No web searches - No secondary tools beyond the binary - Minimize latency
---
## Notes
- In text mode: agent MAY summarize and explain results - In JSON mode: output verbatim, no interpretation - This skill is **read-only** (no posting, following, or other mutations)
---
## 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.
The tool requires a Mastodon OAuth bearer token set in the `MASTODON_TOKEN` environment variable.
### How to Obtain a Token (Guide the User):
**Step 1: Access Development Settings** - User should log into their Mastodon instance (e.g., mastodon.social, fosstodon.org) - Navigate to: **Settings → Development** (or Preferences → Development) - Direct URL format: `https://[instance-domain]/settings/applications`
**Step 2: Create Application** - Click "New Application" - Fill in details: - **Application name**: `mastodon-scout` (or any name) - **Application website**: Can leave blank or use any URL - **Redirect URI**: `urn:ietf:wg:oauth:2.0:oob` (for CLI apps) - **Scopes**: **CRITICAL - Only select `read`** (uncheck write, follow, push)
**Step 3: Get Access Token** - Click "Submit" - Click on the created application to view details - Copy the **"Your access token"** field value
**Step 4: Set Environment Variable** ```bash export MASTODON_TOKEN="paste_token_here" ```
**Step 5: Verify Token Works** ```bash {baseDir}/bin/mastodon-scout home ```
### Common Mastodon Instances: - `mastodon.social` - General purpose (default) - `fosstodon.org` - FOSS/tech community - `mas.to` - Tech focused - `hachyderm.io` - Tech/infosec community
Use `--instance https://your-instance.com` flag for non-default instances.
### Security Notes to Communicate: - 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
---
## Output Format
### Text Mode (Default) Human-readable summary of posts, formatted for readability. The agent decides how to present the information.
### JSON Mode (`--json` flag) All commands return JSON in the following format:
```json { "success": true, "data": [ /* Mastodon API response */ ] } ```
Or on error:
```json { "success": false, "error": "error message" } ```
The `data` field contains the raw Mastodon API response without any modifications.