Developer docs

Start here

Welcome, developer

The portal is your control plane for artifacts. Each artifact corresponds to one GitHub repository. From here you onboard the repo, run the publishing checks, choose visibility, edit display metadata, watch live observability, and moderate reviews: all in one place.

GitHub-only onboarding

Paste a repo URL and we pull the source at HEAD. No ZIPs to upload, no separate registry account to create.

Free observability

The SDK ships with every artifact and streams aggregated usage data into your dashboard. No analytics code required.

SHA-pinned installs

We capture the exact commit at publish time. End users get that SHA: they're insulated from your future force-pushes.

0 → 1

Quickstart

Three steps. Allow about five minutes for a first publish.

2. Paste a repo URL

From My artifacts, click New artifact. Paste a full GitHub URL: e.g. https://github.com/your-handle/skill-pdf. The portal:

Fetches the manifest (or detects a convention file)
Captures the SHA of HEAD on the default branch
Auto-detects the kind (skill / mcp / agent / plugin)
Pre-fills name, slug, description, tags

Don't have a repo yet?

The /artifacts/new page ships with three example repos you can click to pre-fill: useful for kicking the tires before publishing your own.

3. Run checks & publish

Run the synchronous checks on the publish tab. If they're all green, set visibility to public and click Publish to registry. The registry rebuilds its catalog within minutes and your artifact appears in /browse.

Repo requirements

Manifest format

The portal reads one of two formats. Pick whichever fits: both produce identical listings.

Minimum metahub.json

json

{
  "name": "pdf",
  "slug": "pdf",
  "kind": "skill",
  "description": "Read PDF files and extract text or images.",
  "version": "0.1.0"
}

All fields

namerequired: Display name shown in the catalog. 60 chars max.
slugrequired: URL-safe identifier. Unique within kind. lowercase-with-dashes.
kindrequired: One of skill, mcp, agent, plugin.
descriptionrequired: One-line summary, 240 chars max. Used as the catalog teaser and meta description.
versionrequired: Semantic version. We pin installs to this + the SHA.
author: Optional. { name, handle, url }: defaults to your GitHub identity.
tags: Array of strings. Used for search and filtering.
homepage: Optional URL to a docs/landing page.
license: SPDX identifier. Defaults to whatever's in your LICENSE file.

Convention files

If your repo predates metahub, we'll detect:

SKILL.md with frontmatter: the portable skills convention (Claude Code, Claude Desktop). We pull name, description, triggers from the frontmatter.
package.json with an mcp field or a recognized bin: for MCP servers.
plugin.json: for Claude Code plugins.

In all cases you can override by adding a top-level metahub.json; explicit always wins.

Gate before publish

Checks the portal runs

On New artifact and again every time you click Re-publish, the portal runs synchronous checks and shows a report. Publish stays disabled until everything required is green.

repo reachable: We can fetch the default branch and the SHA is captured.
manifest valid: metahub.json (or detected convention) parses and required fields are present.
slug unique: No other artifact of the same kind owns this slug.
README present: At least 200 characters of content. Used as the artifact's detail page.
skill specifics: SKILL.md exists at repo root, frontmatter has name + description.
mcp specifics: package.json has a runnable bin or main entry.
plugin specifics: plugin.json exists with name and kind: "plugin".

Partial reports are OK

One red row doesn't block the others from running. You see all failures at once: fix them in one push instead of playing whack-a-mole.

Who can see it

Visibility states

Visibility is per-artifact and toggled from the artifact overview page. It controls catalog inclusion, not source-code access (we never store private source: we fetch it on demand).

Private

Only you can see the listing. Doesn't appear in /browse or mh search. Useful while you're still iterating.

Unlisted

Reachable by direct link only. Installable with mh install <kind>/<slug> if the user knows the slug. Doesn't appear in catalog listings.

Public

Indexed in the catalog. Searchable, browsable, and listed in the right kind page (/skills, /mcps, etc.).

Public ≠ verified

A public artifact still needs to be verified to be considered "live": i.e. to count toward your portfolio stats and to surface in featured collections.

Verified flag

Set the first time the publish checks all pass and you've captured a SHA. Once verified, your artifact shows the green check on its detail page and the green "live" dot in your dashboard.

Re-publishing a new SHA preserves the verified flag. Verification clears only if you toggle visibility back to private and the SHA is wiped.

Lifecycle

Publishing & re-publishing

Each publish captures one SHA. End users who installed before the publish keep their old SHA; only mh update <slug> pulls the new one. This is deliberate: it gives you a real version frontier without breaking installs the moment you push.

text

v0.1.0  →  abc1234 (Mar 12)  ← initial publish
v0.1.1  →  def5678 (Mar 14)  ← re-publish (current)

To re-publish:

Push commits to your default branch
Hit Re-publish from latest commit on the publish tab
Checks re-run; on green, the new SHA replaces the old

Want auto-publish?

A GitHub App webhook trigger is on the roadmap. Until then, re-publish is one click from the publish tab.

Watch real usage

Observability dashboard

Open /artifacts/<id>/observability on any of your artifacts. Everything is aggregated over a rolling 30-day window. Telemetry arrives in batches every 30 seconds; expect a sub-minute lag.

The four KPI tiles

Invocations: Total successful invocations in the window. A small sparkline shows daily volume. Delta vs. previous 30 days appears below.
Unique installs: Count of distinct installIds. This is the closest proxy you'll get to "monthly active users" without us collecting personal data.
Error rate: Share of invocations the SDK reported as status: "error". Green under 1%, warn 1–5%, red above 5%.
Reviews: Average star rating + total review count.

30-day sparkline

Below the KPIs is a larger sparkline showing the full 30-day invocation curve. Hover individual days to see counts. Zero days are filled in: gaps mean no telemetry was ingested.

Models, tools, handoffs

Four horizontal bar lists round out the page. Each shows the top-N items from the window:

Top models: which LLM invoked the artifact most (claude-sonnet, claude-opus, gpt-4o, local ollama, …). Useful for spotting upgrade migrations.
Top tools: which tools fire alongside the artifact in the host environment. A signal of where it sits in real workflows.
Top handoffs: which other artifact (if any) follows yours in the same session. Hints at natural pipelines you could bundle into a plugin.
Top hosts: Claude Code vs. Cursor vs. Antigravity vs. custom. Tells you which integration surface to invest in.

When it's empty

First publish? The observability tab shows the install command instead of charts. share it on your social or in your README to start the funnel.

Community

Reviews & moderation

How reviews arrive

End users leave reviews from the artifact's detail page on the registry. The registry proxies them to the portal where they appear in two places:

The "Reviews" tab on the artifact (paginated list, sort by date)
The Reviews KPI tile on observability (avg rating + count)

Reviews carry a verified flag if the reviewer signed in to their GitHub account before posting.

Hiding a review

You can hide a review you find inappropriate. Hover the row, click Hide, confirm. The review:

Disappears from the registry detail page within seconds
No longer counts toward the rating average
Replaced by a placeholder in your own reviews tab

One-way action

Hidden reviews can be unhidden via the public API, but the UI currently doesn't expose an unhide button. Use it judiciously: the registry's review feed is a key part of user trust.

Polish the listing

Display metadata

Beyond the manifest, you can edit display-only metadata inline from the artifact overview page. Hover the section, click Edit, type, save. Fields:

displayName: Override the manifest name if you want a more user-facing label (e.g. "PDF Extract" instead of "pdf").
tagline: One-line marketing pitch. Shown above the description on the catalog detail page.
longDescription: Longer prose: up to a few paragraphs. Markdown supported.
category: Free-form grouping label. Future versions will use this for collection pages.
supportUrl, docsUrl: External links. Catalog renders them as outbound buttons.
logoUrl: Square PNG/SVG. Falls back to a generated identicon.

Manifest is source of truth

Display metadata never overrides the manifest's slug, version, or kind. Those still come from the repo.

Per-artifact secret

Per-artifact API keys

Every artifact has a server-side API key (prefix mhi_). The SDK signs ingest payloads with it so telemetry from the wild can be attributed to the right artifact. You'll find it on the artifact's overview page.

Reveal: click the eye icon to show the plaintext. The button stays revealed only as long as the panel is mounted.
Copy: one-click clipboard copy. Use this for CI secrets.
Rotate: generates a new key. Old key stops working immediately. Existing installs continue using their per-install keys, so rotation doesn't break end users: only your own backend integrations.

Treat it like a service token

Don't commit it. Don't paste it in client code. If it leaks, rotate from the panel and grep your CI for the old prefix.

Account-level

Personal access tokens

Personal tokens (prefix mhrg_) let you script the registry from CI or a deploy box. Manage them at /settings.

Each token has a name, prefix, scopes, and a last-used timestamp:

artifacts:read: Read the public catalog. Required for the CLI to look up SHAs at install time.
reviews:write: Forward review submissions on behalf of users. Only the registry runtime needs this.
ingest:write: Write telemetry. Mostly minted automatically as per-install API keys: you only need it directly if you're testing the ingest pipeline.

bash

# Use a token in CI / non-interactive contexts
export METAHUB_SERVICE_TOKEN=mhrg_xxx

# Install an artifact without an interactive login
mh install skills/pdf

Plaintext shown once

When you create a token, the plaintext appears in a green banner with a copy button. After you dismiss it, you can only see the prefix: there's no way to recover the full value. Save it to a password manager immediately.

Optional

CLI helpers for developers

Most developer work happens in the portal UI, but a few CLI commands are handy when you're iterating fast:

bash

mh doctor <kind>/<slug>      # debug a published artifact locally
mh login                     # GitHub Device Flow auth (one-time)
mh list                      # what's installed on this machine

See the full reference on the registry docs.

Quick answers

FAQ

What does it cost to publish?

Nothing. Publishing artifacts, hosting the listing, getting observability: all free for iteration 1. We'll introduce paid tiers (private bundle storage, managed delegate keys, SLA-backed support) later and grandfather existing public artifacts.

Do you store my source code?

We fetch source from your GitHub repo at publish time to capture the SHA and run checks. We don't cache or redistribute it: installs go directly from end users to your repo at the captured SHA.

Can I take an artifact down?

Yes. Toggle visibility to private. The listing disappears from the catalog immediately. End users with existing installs keep working until they uninstall: we don't reach into their machines.

Can two GitHub accounts co-own one artifact?

Not yet: single-owner only in iteration 1. Multi-owner support is on the roadmap behind multi-tenant + org work. In the meantime, an org account that both contributors have push access to is the supported workaround.

Do I have to use the SDK?

Strongly recommended. Without it, you lose all observability: the listing still works but the dashboard stays empty. The SDK is a single import and a one-line wrap call per kind; see the @metahub/skill, @metahub/mcp, and @metahub/agent READMEs in the monorepo.

Ready to ship?

Publish your first artifact.

Paste a GitHub URL, run the checks, and you're live in the registry within minutes.

Start a new artifact Consumer docs