The YourBot Plugin Builder turns a plain-language feature request into an inspectable Python plugin that you can validate, test in Discord, refine in Visual Studio Code, and publish through the YourBot Marketplace. You do not need to build a Discord Gateway connection, host a bot process, create a customer installation flow, or operate a billing system before the feature becomes useful.

Treat the AI output as a first implementation, not an automatic release. Define the behavior, review the manifest and capabilities, test it on a server you manage, refine it in VS Code, then submit it with an accurate listing and support plan.

This guide follows one example from idea to marketplace using the current YourBot SDK v0.9.0.

Editorial disclosure: This guide is published by YourBot.gg and reflects the current Plugin Builder, SDK documentation, Developer Agreement, and marketplace standards. Product limits and commercial rules can change, so use the live Dev Portal as the final source of truth before submission.

The Complete Plugin Journey

The Plugin Builder produces a YourBot SDK plugin, not an unrestricted standalone Discord bot. That is what lets YourBot provide the shared Discord connection, sandbox, storage, dashboards, installation, updates, marketplace, and hosted runtime.

Before You Build: Confirm a Plugin Is the Right Tool

Check three places before generating code:

1. Built-in services: YourBot already provides moderation, Tickets, Analytics, Beacon Events, Group Finder, Join-to-Create Voice, Welcome, Announcements, Giveaways, and Social Feeds.
2. Marketplace: An existing maintained plugin may already solve the problem.
3. Plugin Builder: Use it when the behavior is specific enough that the built-ins and marketplace do not cover it.

A plugin is appropriate for a clear server-owned workflow such as an application process, game roster, searchable record, mentor system, specialized dashboard, approved API integration, or unique automation.

If the plugin needs channels, roles, or permissions that do not exist yet, Start Your Server can prepare that surrounding structure. Keep the two jobs distinct: Start Your Server configures the community; the Plugin Builder creates custom behavior.

Our Example: Resource Review Board

This guide uses a plugin called Resource Review Board.

Members submit a useful link through /resource-suggest. Staff review suggestions in a dashboard and decide whether to approve them for a configured resource channel.

The finished plugin should:

• Accept a title, URL, category, and short explanation
• Store suggestions separately for each Discord server
• Prevent obvious duplicate submissions
• Let administrators choose a reviewer role and publication channel
• Keep pending suggestions limited to authorized reviewers
• Provide approve and reject actions
• Publish approved resources in a consistent format
• Log missing permissions and failed posts
• Expose a dashboard for settings, pending items, and recent decisions

It demonstrates storage, settings, permissions, dashboards, and review without requiring an external API.

Step 1: Write a Production-Quality Plugin Prompt

The Plugin Builder works best when the prompt defines eight things:

Copy-ready prompt

Create a Discord plugin named Resource Review Board.

Members use /resource-suggest to submit a title, URL, category, and short
explanation. Store suggestions per server. Prevent an identical URL from
being submitted twice while it is pending or already approved.

Administrators choose the Reviewer role and Approved Resources channel.
Only members with the Reviewer role may see pending submissions, approve
or reject them, or view private review notes.

When approved, post the title, URL, category, submitter mention, and
explanation in the configured channel. If the channel was deleted or the
bot lacks permission, keep the suggestion pending and show a useful error.

Add an administrator dashboard with:
- settings for reviewer role and publication channel;
- a table of pending suggestions;
- approve and reject actions;
- recent decisions and totals by category.

Use per-server storage, do not require message-content access, add cooldowns
for repeated submissions, and log permission or posting failures. Include
clear command descriptions, validation, and tests where practical.

The prompt says what success looks like. It does not ask the model to invent the product requirements.

Step 2: Choose the Plugin ID Carefully

Choose a stable plugin ID before generation:

resource_review

Current SDK rules require an ID that:

• Is 3–32 characters
• Starts with a lowercase letter
• Uses lowercase letters, digits, and underscores
• Matches the plugin record created in the Dev Portal

Plugin IDs are permanent under the current Developer Agreement. Do not use a temporary joke name, another company’s trademark, or a name that imitates a built-in YourBot feature.

The marketplace name can change later; the permanent ID deserves more care.

Step 3: Plan Before Running the Full Build

The Plugin Builder can perform a lower-cost planning pass before generating the complete source.

Review the proposed:

• Slash commands
• Events and components
• Data model
• Required capabilities
• Outside domains
• Dashboard pages
• Administrator settings
• Error and edge-case behavior

For Resource Review Board, a sensible plan might include:

/resource-suggest
/resource-status
/resource-review

Possible storage:

settings
suggestion:{suggestion_id}
url_index:{normalized_url}
decision:{suggestion_id}

The plugin does not need message-content access because members submit structured slash-command options. It does need key-value storage and the ability to post approved resources. Role checks and dashboard actions may introduce additional capabilities depending on the implementation.

Correct the plan before the full build. A polished prompt cannot rescue the wrong product model.

Step 4: Choose the Current Model, Budget, and Dashboard Option

The builder currently presents model and budget choices in the Dev Portal. Budget presets are designed to give progressively larger plugins more room.

Use the current in-product estimate rather than copying an old example price from a blog post. The builder places a temporary hold, charges according to the tokens actually used, and releases the unused portion when the build settles.

Use the recommended budget for a compact plugin, add headroom for several workflows or a dashboard, and split an oversized product into a reliable first release.

Enable the dashboard option when administrators need settings, review queues, charts, or tables. It can be refined later in the Dev Portal or SDK files.

Step 5: Watch the Build, but Judge the Files

The live build moves through phases such as Reserve, Design, Write, Check, and Ready. You can leave the page; the build continues and appears under Saved builds when complete. Build transcripts are retained, and an interrupted build can be resumed.

The finished files matter more than the progress narration. Review:

• manifest.json
• __main__.py
• requirements.txt, when present
• dashboard_manifest.json, when present
• Any supporting Python or dashboard files
• Registered slash commands
• Requested capabilities
• Requested external domains
• Validator findings

Confirm that the implementation—not only the summary—matches the requirement.

Step 6: Understand the Generated Project

A maintainable project might look like:

resource_review/
├── manifest.json
├── __main__.py
├── resource_logic.py
├── requirements.txt
├── dashboard_manifest.json
├── dashboard/
│   └── index.html
└── tests/
    └── test_resource_review.py

Only manifest.json and __main__.py are required.

manifest.json

The manifest identifies the plugin and declares what it needs.

A simplified version for the example could look like:

{
  "id": "resource_review",
  "name": "Resource Review Board",
  "version": "1.0.0",
  "description": "Collect, review, and publish community resource suggestions.",
  "capabilities_required": [
    "storage:kv",
    "discord:send_message"
  ],
  "slash_commands": [
    {
      "name": "resource-suggest",
      "description": "Submit a resource for staff review",
      "options": [
        {
          "name": "title",
          "description": "Resource title",
          "type": 3,
          "required": true
        },
        {
          "name": "url",
          "description": "Resource URL",
          "type": 3,
          "required": true
        },
        {
          "name": "category",
          "description": "Resource category",
          "type": 3,
          "required": true
        },
        {
          "name": "reason",
          "description": "Why this resource is useful",
          "type": 3,
          "required": true
        }
      ]
    }
  ]
}

Declaring slash commands automatically implies the interaction-response capability. The upload pipeline can detect capabilities used in code and add missing declarations with a warning, but you should still review the final consent surface deliberately.

Python files

Keep __main__.py focused on handler registration:

from yourbot_sdk import Context, Plugin

from resource_logic import save_suggestion

plugin = Plugin()


def option_map(event: dict) -> dict:
    return {
        option["name"]: option.get("value")
        for option in event.get("options", [])
    }


@plugin.on_slash_command("resource-suggest")
def resource_suggest(ctx: Context, event: dict) -> None:
    suggestion_id = event["interaction_id"]
    save_suggestion(ctx, suggestion_id, option_map(event))
    ctx.interaction.respond(
        content=f"Suggestion `{suggestion_id}` was saved for review."
    )


plugin.run()

Put testable product logic in resource_logic.py:

from yourbot_sdk import Context


def save_suggestion(
    ctx: Context,
    suggestion_id: str,
    options: dict,
) -> dict:
    suggestion = {
        "title": options["title"].strip(),
        "url": options["url"].strip(),
        "category": options["category"].strip(),
        "reason": options["reason"].strip(),
        "status": "pending",
    }
    ctx.kv.set(f"suggestion:{suggestion_id}", suggestion)
    return suggestion

This is deliberately small. A production version still needs URL validation, duplicate checks, reviewer authorization, failure handling, and dashboard actions.

Dashboard files

Every plugin can expose a dashboard in one of two modes, documented in the dashboard guide:

• Manifest mode: Define themed widgets in JSON and implement Python RPC handlers.
• Iframe mode: Build a custom HTML, CSS, and JavaScript interface.

Manifest mode is usually the fastest choice for settings, statistics, tables, and forms. Use iframe mode when the interface needs custom interaction or presentation beyond the widget system.

Step 7: Run the Platform Validator Before Commit

Every Plugin Builder draft passes through validation before it can become a committed version.

The validator checks areas such as:

• Manifest structure
• Illegal or missing capabilities
• Slash-command declarations and handlers
• Forbidden imports
• Source that cannot be parsed
• Declared external domains
• Dangerous code patterns

Use the AI correction action for clear findings, then inspect the changes. Validation checks platform rules; it cannot prove that the workflow is correct or understandable.

When ready, commit the draft and keep the downloaded ZIP locally.

Step 8: Dev-Install the Committed Version

Install the committed version on a Discord server you manage before marketplace submission.

Current development installs:

• Expire after 24 hours
• Allow up to three active test installations
• Auto-approve the plugin capabilities on your managed test servers
• Stream live logs and events into the Dev Portal

Test valid and invalid submissions, duplicates, missing configuration, deleted channels, missing permissions, unauthorized review attempts, approve/reject actions, dashboard state, and reinstall behavior.

Auto-approved development capabilities make real testing possible; they do not remove the need to request the correct capabilities or explain them to future customers.

Step 9: Decide Whether to Continue in the Builder or Move to VS Code

Stay in the Builder for prompt-level corrections and early evaluation. Move to VS Code for precise source control, unit tests, Git history, multiple files, dashboard refinement, debugging, developer handoff, or long-term maintenance.

The builder and SDK are not separate ecosystems. The builder writes against the same SDK you use locally.

Setting Up Visual Studio Code for YourBot Plugin Development

Use the full name Visual Studio Code or VS Code. It is different from Microsoft Visual Studio.

Step 10: Install the Local Tools

Install Visual Studio Code, Python 3, Microsoft’s official Python extension, and optionally Git for source control or GitHub releases.

Download the plugin ZIP from the Plugin Builder, extract it into a normal project folder, then choose File → Open Folder in VS Code.

Open the complete folder so VS Code can discover the environment, tests, manifest, and settings.

Step 11: Create a Project Virtual Environment

A Python virtual environment keeps the YourBot SDK and plugin dependencies isolated from other projects.

VS Code interface

Open the Command Palette and run:

Python: Create Environment

Choose Venv, select the Python interpreter, and let VS Code create .venv. Microsoft’s Python environment guide documents the same workflow.

Then run:

Python: Select Interpreter

Choose the interpreter inside the project’s .venv folder. VS Code uses that environment for execution, debugging, IntelliSense, and tests.

Windows PowerShell alternative

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install yourbot-sdk pytest

macOS or Linux alternative

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install yourbot-sdk pytest

Install additional dependencies when present:

python -m pip install -r requirements.txt

If PowerShell blocks activation, select the .venv interpreter in VS Code or invoke its Python directly before changing any execution policy.

Add a .gitignore:

.venv/
__pycache__/
.pytest_cache/
*.pyc

Never put API keys or Discord tokens in this repository. YourBot provides encrypted ctx.secrets for plugin credentials.

Step 12: Verify the Project With the YourBot CLI

The current SDK installs a yourbot command. The canonical command list lives in the SDK quick-start documentation.

Run:

yourbot doctor
yourbot validate

yourbot doctor checks the environment and project health. yourbot validate runs the core upload-pipeline checks locally, including the manifest, capabilities, handlers, imports, and auto-detection.

When the command is not found, confirm that VS Code selected the virtual environment where yourbot-sdk is installed:

python -m pip show yourbot-sdk

The public docs currently identify SDK v0.9.0. Use the live documentation and yourbot doctor as the current source rather than hard-coding it into long-lived setup scripts.

Step 13: Run the Plugin Locally

Create or review events.yaml with representative local events, then run:

yourbot dev

For an edit-and-retest loop:

yourbot dev --watch

The runner fires events.yaml scenarios and streams logs without Docker or Discord. Use local runs for fast logic checks, unit tests for repeatability, and Dev Portal installs for real permissions and server behavior.

Step 14: Add Unit Tests

The SDK includes MockContext and make_event for ordinary Python tests.

Example:

from yourbot_sdk.testing import MockContext

from resource_logic import save_suggestion


def test_resource_suggestion_is_saved() -> None:
    ctx = MockContext(capabilities=["storage:kv"])
    options = {
        "title": "Python venv guide",
        "url": "https://docs.python.org/3/library/venv.html",
        "category": "development",
        "reason": "Explains isolated Python environments.",
    }

    saved = save_suggestion(ctx, "suggestion-1", options)

    assert saved["status"] == "pending"
    assert ctx.kv.get("suggestion:suggestion-1") == saved

Run tests in the terminal:

python -m pytest

VS Code’s Python Test Explorer can discover, run, debug, and show coverage for pytest or unittest. Use Python: Configure Tests when needed.

Step 15: Follow the Runtime Model

Five production rules from the Storage & I/O and Production documentation should shape the code.

Store durable data in platform storage

The filesystem is read-only in production, apart from a small temporary area that does not persist.

Use:

• ctx.kv for per-server JSON settings, counters, and simple records
• ctx.sql for relational data that genuinely needs SQL
• ctx.ephemeral for cooldowns, deduplication, and temporary flags
• ctx.secrets for API keys and signing secrets

Do not rely on module globals or files for durable state.

Make event side effects idempotent

Gateway events can be delivered at least once. A handler may see the same event more than once.

Use stable identifiers and ctx.ephemeral.dedup(...) when duplicate execution would repeat a side effect.

Request message content only when needed

Without events:message_content, message events arrive with metadata rather than text and related rich fields. Slash-command options and component values remain available.

Resource Review Board does not need to read ordinary messages, so it should not request this capability.

Use the controlled network APIs

Marketplace plugin containers have no direct network access.

Use ctx.http for approved HTTP domains and ctx.ws for declared WebSocket hosts. Declare the domains in proxy_domains_requested and explain them on the marketplace listing.

Handle typed SDK errors

Catch relevant errors such as:

• CapabilityError
• SdkPermissionError
• RateLimitError
• DiscordApiError
• ValidationError
• KvQuotaError

Log actionable context without exposing secrets or unnecessary private content.

Current scheduling documentation note

The public Build and Production pages document manifest-declared cron jobs in UTC with a five-minute minimum and up to five entries. The current Getting Started page also contains a note telling developers to skip the cron template. Because those instructions conflict, verify the current Dev Portal behavior before making scheduled delivery a critical release requirement.

Step 16: Keep the Package Within Platform Limits

Current package limits are:

• 25 MB compressed
• 100 MB uncompressed
• 500 files
• 10 MB per individual file

manifest.json and __main__.py must sit at the ZIP root.

Exclude .venv, caches, screenshots, raw data, local logs, and source-control metadata.

A correct ZIP should open directly to:

manifest.json
__main__.py
requirements.txt
dashboard_manifest.json
...

It should not contain one extra outer folder above those files.

Onboarding the Plugin to YourBot

Step 17: Accept the Developer Agreement

The current Marketplace Developer Agreement must be accepted in the Dev Portal before you can:

• Create a plugin listing
• Submit a version for publication
• Connect a payout account
• Offer paid plans

Developers must be at least 18 or the age of majority in their jurisdiction, whichever is older. A company representative must have authority to bind the company.

The developer retains ownership of the plugin code and listing content. The agreement grants EmberStream Studio LLC the license required to host, execute, distribute, display, and promote the plugin through YourBot.

Read the current Developer Agreement before publishing. This guide is not legal or tax advice.

Step 18: Create the Plugin Record in the Dev Portal

Create the Dev Portal record with the same permanent ID as the manifest: resource_review. The two IDs must match.

The Dev Portal—not manifest.json—stores the display name, description, byline, icon, tags, screenshots, support contact, and marketplace copy.

The platform assigns and stamps the uploaded version number, so you do not need to manually change the manifest version before each ZIP upload or GitHub pull.

Step 19: Choose ZIP Upload or GitHub

You can ship versions in either of two ways:

Upload a ZIP

Use ZIP uploads for a simple private project, an early Builder artifact, or deliberate manual release control.

Run yourbot validate, create a clean ZIP, and upload it through the Dev Portal.

Connect GitHub

Use GitHub for long-term maintenance, collaboration, source history, or frequent releases.

Private repositories must grant YourBot enough read access for source review. Public repositories may qualify established developers for a faster trusted-publishing path when no security-relevant change or flagged scan requires review.

Regardless of source, the same validation, capability, sandbox, and review rules apply.

Step 20: Create an Installable Version and Test Again

After upload, review detected capabilities and domains, commands, dashboard preview, and changelog. Dev-install that exact version, repeat the Discord test plan, inspect logs, and confirm cleanup.

This final test matters because local files can differ from the version you actually uploaded.

Step 21: Build a Marketplace Listing That Earns Trust

A good listing explains the customer outcome, not the build process.

Include:

Clear opening

Collect community resource suggestions, route them to an authorized review
queue, and publish approved links in a consistent server resource channel.

Explain the commands, dashboard, settings, review controls, duplicate protection, and published output.

Permissions and capabilities

Explain why each is needed:

Do not request access for a hypothetical future version.

Data handling

State what is stored, who can access it, whether it leaves YourBot through an approved domain, how deletion works, and why personal data is necessary.

If personal data is sent off-platform, the Developer Agreement requires an accurate listing disclosure and a privacy notice.

Screenshots

Show the real command response, settings page, review queue, and approved post. Do not use concept art that implies behavior the plugin does not provide.

Support

Provide a working support contact and set realistic expectations. Paid plugins require reasonable customer support under the Developer Agreement.

Step 22: Configure Installation Plans

A plugin needs at least one plan before customers can install it.

The current platform supports up to five plans per plugin: a no-charge option, monthly, yearly, or one-time billing, with optional seats, trials, sales, bundles, and gifting.

Current legal terms list a $3 minimum for a paid plan and trials up to 14 days.

For paid plans, connect Stripe Express from Earnings, complete verification, confirm charges and payouts are enabled, and test checkout and entitlements.

YourBot acts as merchant of record for marketplace sales. Current developer shares range from 70% to 85% based on trailing 30-day sales net of refunds, with a rolling hold before Stripe payout.

Step 23: Submit for Review

Before submission, run:

yourbot doctor
yourbot validate
python -m pytest

The publication pipeline checks:

• Required manifest fields
• Legal capabilities and domains
• Slash-command validity and reserved names
• Disallowed imports and unsafe code patterns
• SQL safety
• Dashboard changes
• Accurate feature and privacy disclosures

Every uploaded version receives automated validation. New developers’ submissions receive human review. Current documentation describes a 24-hour review target while the Developer Agreement makes clear that review targets are estimates, not guarantees.

If denied, fix the specific Dev Portal feedback and submit a new version. Approval is not a certification or warranty; the developer remains responsible.

Step 24: Publish, Roll Out, and Maintain

After approval, publish with a changelog, test updates before release, use staged rollout when risk warrants it, monitor errors and support, and keep access declarations accurate.

Marketplace installations default to managed updates. A server owner can pin a published version, which disables automatic updates for that installation.

Adding a new capability or external domain pauses the update for affected servers until the administrator consents. Removing access does not require the same additional approval.

The optional Quality designation is separate from basic publication. It requires a manual staff test, representative screenshots and description, an update within the previous 90 days, and a developer who responds to reports.

Common Plugin Builder and SDK Mistakes

Asking the AI to decide the product

“Build a useful moderation plugin” is not a specification. Define the problem, rules, settings, and failures.

Choosing a careless permanent ID

The marketplace name can evolve. The permanent plugin ID cannot be treated casually.

Approving every capability

Use the smallest access set that supports the current release. Broader access increases review friction and customer concern.

Using message events when slash commands are enough

Structured commands often avoid the need for message-content access and produce clearer inputs.

Treating local simulation as production testing

yourbot dev cannot reproduce every Discord permission, role hierarchy, or deleted-resource failure. Use a Dev Portal test install.

Storing state in files or module globals

The filesystem is not durable, and pooled workers restart. Use YourBot storage.

Forgetting idempotency

At-least-once event delivery can repeat a side effect. Deduplicate anything that must happen once.

Uploading the wrong ZIP shape

The package root must contain manifest.json and __main__.py.

Publishing developer notes as customer copy

Customers need outcomes, setup, permissions, data handling, screenshots, pricing, and support—not internal build notes.

Adding sensitive data without a retention reason

Collect only what the feature needs. Avoid storing private text merely because storage is available.

Frequently Asked Questions

Can I build a YourBot plugin without coding?

Yes. The Plugin Builder can plan and generate a YourBot SDK plugin from a written specification. You still need to review, validate, and test the result.

Does the Plugin Builder create a standalone Discord bot?

No. It creates a plugin for the YourBot SDK and hosted runtime. The files are inspectable and downloadable, but they are not automatically a complete independent Discord application.

Do I need Visual Studio Code?

No. You can review, test-install, and submit a generated plugin through the Dev Portal. VS Code becomes valuable for direct editing, tests, Git, debugging, and long-term maintenance.

Can I edit the generated source?

Yes. Download the ZIP, open the project in VS Code, install yourbot-sdk, then use the CLI and normal Python tools.

Do I need Docker or a VPS?

No. yourbot dev runs locally without Docker, and YourBot operates published plugins in the managed marketplace runtime.

Can my plugin call an outside API?

Yes, through ctx.http or ctx.ws and declared domains approved by the installing administrator. Marketplace containers do not have direct network access.

Can my plugin have a dashboard?

Yes. Use manifest mode for platform-styled widgets or iframe mode for custom HTML, CSS, and JavaScript.

Can I sell the plugin?

Yes. Accept the Developer Agreement, complete Stripe Connect onboarding, configure an eligible plan, pass review, and provide ongoing support.

Who owns the plugin code?

The developer retains ownership. The Developer Agreement grants YourBot the license needed to host, execute, distribute, display, and promote it through the platform.

What happens when I publish an update?

Servers using managed updates can receive it automatically. Pinned installations remain on their selected version, and added capabilities or domains require administrator consent before the update proceeds.

Final Verdict

The YourBot Plugin Builder is the fastest entry point, not the end of the development process.

Describe a precise feature. Review the plan, source, manifest, commands, capabilities, and dashboard. Commit the draft and test it in a real server. Move to VS Code when you need direct control, then use the SDK’s local runner, validator, health checks, and test utilities before uploading the finished version.

The Dev Portal connects that development work to the marketplace: permanent plugin identity, versions, dashboards, plans, review, test installs, Stripe onboarding, publication, staged releases, automatic updates, and customer support.

Open the Plugin Builder, review the YourBot SDK documentation, and build the smallest reliable version of the plugin before expanding its roadmap.