Skip to Content
Sophon Docs
Marketplace

Publishing Packages

Package a skill, plugin, or agent, publish through the web dashboard or the publish API, and move through review to an approved release.

Anyone with a marketplace account can publish packages. This page walks the full path: naming and versioning rules, packaging a skill, plugin, or agent, the publish routes, and what happens in review.

Before you publish

You need a marketplace account with a verified email address.

Names are claimed on first publish and are permanent:

  • Lowercase letters, digits, and hyphens; must start with a letter or digit; 2–64 characters (pattern ^[a-z0-9][a-z0-9-]{1,63}$)
  • Globally unique across the whole marketplace
  • Immutable — a name can't be changed or transferred after it's claimed

Versions follow strict semantic versioning (major.minor.patch, prerelease suffixes like -beta.1 allowed), and every new version must be strictly greater than every version you've ever submitted — including rejected ones. A rejected version number is burned; bump and resubmit.

Packaging a skill

A skill ships as a .sophon-skill archive (a zip) containing:

  • manifest.json — the package descriptor: name, version, description, author, license, category, the runtime (python, csharp, or sandbox), the entrypoint file, the tools the skill exposes (each with a name, description, and risk level from none to critical), and a permissions block declaring up front what the skill needs: network hostnames, filesystem paths, memory (maxMemoryMb, up to 4096), and CPU time (maxCpuSeconds).
  • The entrypoint code — main.py or main.cs, implementing each tool.
  • SKILL.md (recommended) — the natural-language guide agents read after install to decide when and how to use the skill (see anatomy of a skill).
  • README.md (optional, up to 64 KB, at the archive root) — rendered as your package's detail page. Write it for the person deciding whether to install.

The full field-by-field schema is in the Skill Manifest Reference. DevStudio can scaffold, validate, and package skills for you.

Declare permissions honestly and minimally — the permissions block is shown to reviewers, displayed on your package page, and presented to every user at install time. A skill that requests more than it needs reviews slower and installs less.

Packaging a plugin

A plugin ships as a .sophon-plugin archive containing:

  • manifest.json — the same descriptor fields, plus "type": "plugin" and a pluginInterface naming which of the five extension interfaces it implements: ChannelAdapter, DocumentExtractor, ModelProvider, EmbeddingProvider, or VaultBackend. Interface-specific fields ride alongside it — channelType for channel adapters, supportedExtensions for document extractors — and a settings[] block declares the configuration the plugin needs (entries of type secret are stored in the vault and masked everywhere). The full field-by-field schema is in the Plugin Manifest Reference.
  • publish/ — the compiled .NET output, containing at least one .dll.

sophon dev build validates the manifest and produces the .sophon-plugin archive for you.

Two interfaces are consumed by the runtime today: ChannelAdapter and DocumentExtractor. Manifests declaring ModelProvider, EmbeddingProvider, or VaultBackend are accepted but not yet consumed — those extension points are coming. A pluginInterface of Tool is refused at parse time by design: custom tools belong in skills, which run sandboxed, or in an MCP server — not in a full-trust plugin process.

Plugins run as full-trust local processes on the installing instance, so they're held to the highest review bar — agent-initiated plugin installs are Critical-risk and always require the user's approval. Note that installing a plugin doesn't start it: it only runs once the instance enables Sophon:Plugins:Enabled (see the Plugins guide).

Packaging an agent

Since v2.2.0 an agent ships as a .sophon-agent archive: manifest.json with "type": "agent", a non-empty SOUL.md, and optionally VOICE.md, HEARTBEAT.md, TOOLS.md, README.md and LICENSE, all at the archive root. It carries no code, and the manifest cannot set autonomy, a pinned model or a delegation allow-list; users turn those on themselves. To publish, the manifest also needs displayName, description, author, license, category, agent.whenToUse and sophon.minVersion.

sophon dev new agent acme-research-helper --author "Acme"
sophon dev validate
sophon dev build      # dist/acme-research-helper.sophon-agent

An agent archive has its own, smaller limits: at most 16 entries, 64 KiB per file, 512 KiB uncompressed and 1 MiB compressed. Legacy agent.json projects cannot be built or published; migrate them first. The format, the fields and the migration steps are in Agent Packages.

Archive limits

For skills and plugins:

  • Package archive: up to 100 MB
  • Uncompressed contents: up to 500 MB, at most 10,000 entries
  • Archives are inspected before acceptance — malformed zips, path-escape attempts, and decompression-bomb patterns are rejected at upload

Publishing via the dashboard

The publisher dashboard has an upload wizard: drop your archive, and it parses the manifest in your browser and previews exactly what will be published — name, version, tools, permissions — before you submit. It accepts .sophon-agent files too.

Publishing via the API

For CI pipelines, mint a publish-scoped API key under Dashboard → API keys. Keys are prefixed smk_ and shown exactly once. Then:

curl -X POST https://marketplace.sophon.buildersoft.io/api/v1/publish \
  -H "Authorization: Bearer smk_..." \
  -F "package=@my-skill-1.2.0.sophon-skill"

A successful publish returns the accepted name, version, checksum, and a pendingReview status. Publish keys can only publish — they can't manage your account, keys, or packages.

Since v2.2.0 the CLI does the same from a project folder, for any package type: sophon dev publish --key smk_… builds and uploads it. The key can also come from SOPHON_MARKETPLACE_KEY, and it never appears in any output.

Publishing an agent from Sophon

An agent you built in Sophon can be published without a project folder: Agent → Publish to Marketplace in the Dashboard, or sophon agents publish <id>. This goes through the marketplace account linked in Settings → Marketplace, with publishing allowed. A link made before 2.2.0 is review-only and must be re-linked. Publishing someone else's agent needs an acknowledgement that you have the right to, and a different name. See Agent Packages.

The review lifecycle

Every version you publish — including the first version of a new package — starts as pending review and is invisible to browse, search, and download until a moderator approves it.

Reviewers work from an automatically generated report: the archive's file inventory, a risk summary of the declared permissions and tool risk levels, and a diff against your previous approved version. Outcomes:

  • Approved — the version goes live; if it's your highest version, it becomes the package's "latest".
  • Rejected — the version never becomes visible; the version number can't be reused, so fix and republish with a bump.

Publishing an update to an already-approved package keeps your current version live while the new one waits in review — your users see no gap.

An agent version is approved only when each skill it requires exists on the marketplace at the required version.

After release

From the publisher dashboard you can:

  • Watch stats — installs and downloads over the last 30 days, per package
  • Deprecate a version — it stays downloadable, but installers see your deprecation message; you can undeprecate at any time
  • Respond to the market — read your reviews and ratings
  • Rotate API keys — revoke and re-mint publish keys

If a shipped version turns out to be harmful, moderators can revoke it — downloads stop immediately.

For agents, revoking goes further: installed copies of a revoked version stop running until each user keeps using it or takes another version. Revoke only for a real problem, and deprecate a version to stop it being offered.

Where to go next