agentic-govbot/PLATFORM_SKILLS.md

Mastodon Platform Skills

Complete listing of all platform-specific governance skills available through the Mastodon API.

Overview

The bot now implements 35+ platform skills organized into 7 categories:

• Account Moderation (9 skills)
• Account Management (4 skills)
• Report Management (4 skills)
• Federation Management (4 skills)
• Security Management (4 skills)
• Instance Administration (2 skills)
• Web-Only Actions (2 skills - informational only)

Account Moderation Skills

suspend_account

Description: Suspend a user account (reversible, blocks login and hides content) Parameters:

• account_id (str): Account ID to suspend
• reason (str): Reason for suspension Reversible: Yes (use unsuspend_account) Authorization: Requires moderation authority per constitution

unsuspend_account

Description: Lift suspension from an account Parameters:

• account_id (str): Account ID to unsuspend Reversible: Yes (can suspend again) Authorization: Requires moderation authority per constitution

silence_account

Description: Silence a user account (hide from public timelines, reversible) Parameters:

• account_id (str): Account ID to silence
• reason (str): Reason for silencing Reversible: Yes (use unsilence_account) Authorization: Requires moderation authority per constitution

unsilence_account

Description: Lift silence from an account Parameters:

• account_id (str): Account ID to unsilence Reversible: Yes (can silence again) Authorization: Requires moderation authority per constitution

disable_account

Description: Disable local account login (reversible) Parameters:

• account_id (str): Account ID to disable
• reason (str): Reason for disabling Reversible: Yes (use enable_account) Authorization: Requires moderation authority per constitution

enable_account

Description: Re-enable a disabled local account Parameters:

• account_id (str): Account ID to enable Reversible: Yes (can disable again) Authorization: Requires moderation authority per constitution

mark_account_sensitive

Description: Mark account's media as always sensitive Parameters:

• account_id (str): Account ID to mark
• reason (str): Reason for marking sensitive Reversible: Yes (use unmark_account_sensitive) Authorization: Requires moderation authority per constitution

unmark_account_sensitive

Description: Remove sensitive flag from account Parameters:

• account_id (str): Account ID to unmark Reversible: Yes (can mark sensitive again) Authorization: Requires moderation authority per constitution

delete_status

Description: Delete a status/post (permanent) Parameters:

• status_id (str): Status ID to delete
• reason (str): Reason for deletion Reversible: No Authorization: Requires moderation authority per constitution

Account Management Skills

approve_account

Description: Approve a pending account registration Parameters:

• account_id (str): Account ID to approve Reversible: No Authorization: Requires account approval authority per constitution

reject_account

Description: Reject a pending account registration (permanent) Parameters:

• account_id (str): Account ID to reject Reversible: No Authorization: Requires account approval authority per constitution

delete_account_data

Description: Permanently delete all data for a suspended account (IRREVERSIBLE) Parameters:

• account_id (str): Suspended account ID to delete Reversible: No Note: Account must already be suspended before data deletion Authorization: Requires highest level authority per constitution

create_account

Description: Create a new user account (requires email verification, may need approval) Parameters:

• username (str): Desired username
• email (str): Email address
• password (str): Account password
• reason (str, optional): Registration reason (if approval required) Reversible: No Limitations:
• User must verify email before account is active
• May require manual moderator approval depending on instance settings
• Only creates regular user accounts (not admin accounts) Authorization: Requires account creation authority per constitution

Report Management Skills

assign_report

Description: Assign a report to yourself for handling Parameters:

• report_id (str): Report ID to assign Reversible: Yes (use unassign_report) Authorization: Requires report management authority per constitution

unassign_report

Description: Unassign a report so others can claim it Parameters:

• report_id (str): Report ID to unassign Reversible: Yes (can reassign) Authorization: Requires report management authority per constitution

resolve_report

Description: Mark a report as resolved Parameters:

• report_id (str): Report ID to resolve Reversible: Yes (use reopen_report) Authorization: Requires report management authority per constitution

reopen_report

Description: Reopen a closed report Parameters:

• report_id (str): Report ID to reopen Reversible: Yes (can resolve again) Authorization: Requires report management authority per constitution

Federation Management Skills

block_domain

Description: Block federation with a domain Parameters:

• domain (str): Domain to block
• severity (str): Block severity: "silence", "suspend", or "noop"
• public_comment (str): Public reason for block
• private_comment (str, optional): Internal note
• reject_media (bool, optional): Reject media files from domain
• reject_reports (bool, optional): Reject reports from domain
• obfuscate (bool, optional): Hide domain name publicly Reversible: Yes (use unblock_domain) Authorization: Requires federation management authority per constitution

unblock_domain

Description: Remove domain from block list Parameters:

• block_id (str): Domain block ID to remove Reversible: Yes (can block again) Authorization: Requires federation management authority per constitution

allow_domain

Description: Add domain to allowlist (for LIMITED_FEDERATION_MODE) Parameters:

• domain (str): Domain to allow Reversible: Yes (use disallow_domain) Authorization: Requires federation management authority per constitution

disallow_domain

Description: Remove domain from allowlist Parameters:

• allow_id (str): Domain allow ID to remove Reversible: Yes (can allow again) Authorization: Requires federation management authority per constitution

Security Management Skills

block_ip

Description: Block IP address or range Parameters:

• ip (str): IP address with CIDR prefix (e.g., "192.168.0.1/24")
• severity (str): Block severity: "sign_up_requires_approval", "sign_up_block", or "no_access"
• comment (str): Reason for IP block
• expires_in (int, optional): Expiration time in seconds Reversible: Yes (use unblock_ip) Authorization: Requires security management authority per constitution

unblock_ip

Description: Remove IP block Parameters:

• block_id (str): IP block ID to remove Reversible: Yes (can block again) Authorization: Requires security management authority per constitution

block_email_domain

Description: Block email domain from registrations Parameters:

• domain (str): Email domain to block (e.g., "spam.com") Reversible: Yes (use unblock_email_domain) Authorization: Requires security management authority per constitution

unblock_email_domain

Description: Remove email domain from block list Parameters:

• block_id (str): Email domain block ID to remove Reversible: Yes (can block again) Authorization: Requires security management authority per constitution

Constitution Management Skills

publish_constitution

Description: Post constitution as pinned thread (deprecates previous version) Parameters:

• constitution_text (str): Full constitution text in markdown
• change_summary (str, optional): Summary of what changed Reversible: No Authorization: Requires constitutional amendment process Behavior:

1. Finds previously pinned constitution (if any)
2. Adds deprecation notice to old version
3. Splits constitution into thread-sized chunks (~450 chars each)
4. Posts as public thread
5. Pins new thread to profile
6. Unpins old thread
7. Saves post ID for future updates

update_profile

Description: Update bot profile information (bio, fields, display name) Parameters:

• display_name (str, optional): Display name
• note (str, optional): Bio/description
• fields (list, optional): Profile fields (max 4, each with 'name' and 'value') Reversible: Yes Authorization: Requires governance approval Example fields:

[
  {"name": "Constitution", "value": "📜 See pinned post"},
  {"name": "Governance", "value": "Consensus-based"},
  {"name": "Source", "value": "github.com/..."}
]

Instance Administration Skills

⚠️ IMPORTANT: Role management is NOT available via the Mastodon API. See "Platform Limitations" section below for details.

Web-Only Actions (Not Available via API)

These skills are included in the bot's knowledge so it can explain limitations to users.

update_instance_rules

Description: Update instance rules/code of conduct Status: WEB-ONLY - Must be done through admin interface Web Interface: /admin/server_settings/rules Note: Mastodon API does not provide endpoints for managing server rules programmatically

create_announcement

Description: Create an instance-wide announcement Status: WEB-ONLY - Must be done through admin interface Web Interface: /admin/announcements Note: Mastodon API does not provide endpoints for creating announcements programmatically

Platform Limitations

The bot is now aware of the following limitations and can explain them to users:

Actions Requiring Web Interface

• Instance Rules: Creating and editing server rules must be done at /admin/server_settings/rules
• Announcements: Creating instance-wide announcements must be done at /admin/announcements
• Role Management: ALL role operations (grant/revoke moderator, admin, or custom roles) must be done at /admin/roles
• Instance Settings: Modifying instance description, contact info, etc. requires web admin access

Actions Not Possible via API

• Role Management: The Mastodon API does NOT support granting or revoking ANY roles (moderator, admin, or custom). You must use:
  • Web interface: /admin/roles
  • Command line: tootctl accounts modify username --role RoleName
• Admin Account Creation: Admin accounts cannot be created via API:

  RAILS_ENV=production bin/tootctl accounts create username --email user@example.com --confirmed --role Owner
  

General Limitations

• Account Creation: New accounts require email verification and may require manual approval depending on instance settings
• Permissions Required: All admin actions require both OAuth scopes AND appropriate role permissions (Manage Users, Manage Reports, etc.)
• Rate Limits: API endpoints are subject to rate limiting
• Suspended Account Deletion: Account data can only be deleted for already-suspended accounts

How It Works

1. Skill Discovery: When a user makes a request, the bot receives the full list of platform skills
2. Limitation Awareness: The bot also receives information about what's not possible via API
3. Intelligent Routing: The LLM agent decides whether to:
   • Execute a platform skill (if available and authorized)
   • Explain a limitation (if requested action requires web interface)
   • Create a governance process (if actor lacks authority)
   • Respond with information (if just asking a question)

Example Interactions

Successful Platform Skill Execution

User: @govbot please suspend account 12345 for spam
Bot: I've suspended account 12345 for spam.
     This action is reversible using the unsuspend_account skill.

Web-Only Limitation

User: @govbot please update the instance rules
Bot: Instance rules cannot be updated via the API.
     To update server rules, please visit:
     https://your-instance.com/admin/server_settings/rules

     You can add, edit, or remove rules through the admin interface.

Account Creation with Limitations

User: @govbot create an account for newuser@example.com
Bot: Account @newuser created successfully.

     Important: The user must verify their email before they can log in.
     Depending on instance settings, manual approval may also be required.

Technical Implementation

Code Changes

1. Mastodon Adapter (src/govbot/platforms/mastodon.py):

   • Added 35+ platform skills across 7 categories
   • Implemented execution methods for all API-available skills
   • Added get_platform_limitations() method to document limitations
   • Web-only skills return helpful messages with admin interface URLs

2. Governance Agent (src/govbot/agent.py):

   • Updated process_request() to accept platform_limitations parameter
   • Enhanced decision-making prompt to include limitation information
   • Agent now explains limitations when users request unavailable actions

3. Bot Integration (src/govbot/bot.py):

   • Retrieves platform limitations alongside platform skills
   • Passes limitations to agent for informed decision-making

API Requirements

All admin skills require:

• Appropriate OAuth scopes (admin:read, admin:write, etc.)
• Role permissions (Manage Users, Manage Reports, Manage Federation, etc.)
• Active Mastodon.py connection with admin access token

Documentation Sources

• Mastodon Admin Accounts API
• Mastodon Admin Reports API
• Mastodon Admin Domain Blocks API
• Mastodon Admin IP Blocks API
• Mastodon Admin Email Domain Blocks API
• Mastodon Accounts API
• Mastodon OAuth Scopes