Mastodon Agent Skill

Mastodon

Purpose

Read and write the user's Mastodon account: verify the connection, list own toots, list followers, publish toots (with native scheduling via scheduled_at), upload media for toots. Use when the user mentions Mastodon or the fediverse.

Tooling

All commands go through bin/mastodon.py:

bin/mastodon.py verify --host https://mastodon.social                                  # verify the token (own profile)
bin/mastodon.py my-posts --host https://mastodon.social --limit 20                     # recent toots
bin/mastodon.py followers --host https://mastodon.social --limit 20                    # own followers
bin/mastodon.py post --host https://mastodon.social --text "hello"                     # confirm first
bin/mastodon.py post --host https://mastodon.social --text "later" --scheduled-at "2026-09-17T09:00:00Z" --visibility unlisted
bin/mastodon.py media-upload --host https://mastodon.social --file ./pic.png --description "alt text"  # returns a media id for post --media-ids

Auth

• Provider id: mastodon (credential is collected as custom.mastodon)
• Collection: provider OAuth via the secure credential flow (credentials.request_api_access). Fully self-serve: register an app on your own instance with POST /api/v1/apps, or generate a personal token under Settings > Development on your instance.
• Required scopes: read, write, follow, push (granular scopes such as write:statuses also work)
• Allowed hosts: your Mastodon instance host, declared at connect time (the --host you pass, e.g. https://mastodon.social; it must start with http:// or https://). The credential is only ever sent to that host.
• Status check: bin/mastodon.py verify --host <your-instance> (must return "ok": true)

Operating Rules

• post is a public write: confirm the text and visibility, plus any attachments, with the user before publishing, unless standing permission exists. Scheduled toots go out unattended, so confirm those too.
• Toots are limited to 500 characters; the CLI rejects anything longer rather than truncating, so keep posts short or split them.
• Instance rules apply: label bot accounts where your instance asks, and note that some instances disable open app registration.
• Reading (verify, my-posts, followers, media-upload) needs no confirmation.
• Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/mastodon.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/mastodon.py

Maturity

🧪 Draft: written from Mastodon's public API docs via the verified research dossier; not yet live-tested end-to-end.