Publishing Packages

Anyone with a marketplace account can publish packages. This page walks the full path: naming and versioning rules, packaging a skill or plugin, the two 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).

Archive limits

• 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.

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.

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.

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.

Where to go next

• Sophon Marketplace overview
• Skill Manifest Reference — every skill manifest field
• Plugin Manifest Reference — every plugin manifest field
• DevStudio — build, test, and package skills in an IDE