Publish a public datapack

Author a shareable datapack as reviewed source, and keep it current

A public datapack is one you share by link so other people's agents can query it. This guide covers the process Yugabyte uses for its own: authoring the content as files under review, publishing with a tool, and refreshing it without duplicating anything.

The packs and the tool live in the repository at meko/datapacks/.

Why the content is a file, not a portal session

A datapack has no export and no import. A pack authored only in the portal cannot be reviewed, diffed, rolled back or rebuilt, and a pack worth sharing is one that keeps changing. Keeping the chapters in a repository makes each refresh an ordinary change with review and history, and makes the cloud datapack a build artifact of it.

Four questions. A pack that fails any of them is a blog post, and a blog post is cheaper.

  1. Do you get the value by asking your agent, not by reading the page? If the content reads fine top to bottom, publish a page.
  2. Do many people care, and do they already run an agent that speaks MCP? An audience that has to adopt an agent first is a longer sell.
  3. Does forwarding it make the sender look good? A war story, a saved afternoon, or a number.
  4. Does it keep changing? Otherwise the link gets read once and dropped. Name who keeps that true and how often.

Each answer is a required field in the pack's manifest, so the test is applied at review time rather than remembered.

What a pack contains

<slug>/
  pack.yaml            manifest: name, description, share role, the four answers
  knowledge/*.md       chapters, one knowledge-base document each
  memories/facts.yaml  short fact-shaped lines
  questions.yaml       what the pack must be able to answer
  pack.lock.json       written by the publisher; committed

Chapters versus facts

Prose belongs in knowledge/: that is what retrieval over a long document is for, and a chapter is the unit a reader forwards. Short declarative statements belong in memories/facts.yaml, where a single statement is stored as written.

The name and the description are the whole first impression

Opening a share link shows the datapack's name and description and nothing else, and a signed-out visitor is asked to sign in before even that. Write both as if they were the only copy a reader sees, because they are. Everything else persuading someone to join belongs in the message that carries the link.

Publish

cd meko/datapacks/packctl

# offline, no credentials. This is what CI runs.
go run . validate
go run . plan ../my-pack

export MEKO_API_KEY=mko_tkn_...                 # Settings > API Keys
export MEKO_DATAPACK_ID=...                     # the datapack to publish to

go run . publish ../my-pack                     # dry run: prints the plan, sends nothing
go run . publish ../my-pack --apply
go run . ask ../my-pack                         # read what the pack answers

publish is a dry run unless you pass --apply.

Refreshing

publish converges. It compares each chapter's SHA-256 against pack.lock.json and touches only what changed, so re-running on an unchanged pack does nothing.

A knowledge-base file cannot be updated in place, so an edited chapter is uploaded first and the old document deleted second. That order is deliberate: a failure between the two leaves both versions of the chapter in the pack, which you can fix, rather than neither.

Two consequences to expect:

  • A refreshed chapter gets a new document id.
  • It re-fires the document_uploaded event, so a refresh looks like new uploads in your analytics.

Editing a fact

publish reports an edited fact and writes nothing, because adding it again would leave two memories making different claims and there is no update path. Delete the memory the plan names, remove its entry from the lock, then publish.

Check that the pack answers, not just that it uploaded

A successful publish proves the bytes landed. It does not prove a reader gets a good answer: a chapter that chunks badly fails silently, and retrieval can return the right passage in the wrong position, which produces a confident answer built on the wrong context.

So each pack carries questions.yaml - the questions a reader will actually ask - and packctl ask runs them and prints what came back. Read the answers. It deliberately does not grade them: whether an answer is good is a judgement about prose, and a threshold tuned on one pack starts failing refreshes of the next.

Limits

Validation holds every pack to the Free limits regardless of your plan, because a pack exists to be read by strangers and most of them are on Free: 5 MB per chapter and 100 MB per account. Chapters may be .md, .txt, .json or .csv.

Next steps