The skills bundle

What an agent needs to know to write the Mzizi language and build with Mzizi ships as an npm package of agent skills, @nyuchi/mzizi-skills. Give an agent the skills so it has the doctrine to hand instead of guessing. Five skills, from the bundle’s index.json at version 0.8.5 (the latest on npm on 30 September 2026):

Skill	What it covers
`mzizi-language`	Writing and checking `.mz`: `LANGUAGE-TRACKER.md` as the one list of what Mzizi can and cannot do (check it before claiming anything), the component syntax, the backend `service` syntax (routes, handlers with `when`, `header` and `respond`, and `example` and `ensure` contracts; RFC-0011), the `mz check --agent` loop and its NDJSON diagnostics, `mz fix`, `mz contract` (a component’s contract, or a service run in process), `mz build` (a service lowered to a local Rust + axum package), the diagnostic codes you will meet, the harness as designed in RFC-0012 (a draft; only the agent protocol exists), and what is not built yet (expressions, bindings, callable functions, loops, error handling, modules, a standard library, component lowering, a release)
`mzizi-roots`	Mzizi’s components, Rust first: `cargo add mzizi-roots` and `mzizi-roots-server`, what `mzizi_get_component` returns, the node-to-crate map, contracts, the two frontend paths (Astro with Roots, or pure Rust) and app setup, reuse before build, and contributing a component
`mzizi-design`	The design system and brand: the 21-family palette and its generated stylesheets, the radius scale, type, pill buttons and the 48px touch floor, status and surface tokens, the brand constellation, the Ubuntu pillars and principles, and the wordmarks
`mzizi-backend`	A Mzizi service on Cloudflare Workers: where it stands today (every live Mzizi Worker is TypeScript; the language’s `service` slice runs in process under `mz contract` and lowers with `mz build` to a local Rust + axum package, with no Workers target and nothing deployed), the endpoint map, a Rust Worker as a sans-IO core plus a thin host, an MCP server over bundled data, the free-except-Fundi access rule, publishing and deploying
`discoverability`	SEO and AIO: link previews, search engines and AI agents, the hive OG-image template, build-time OG images on static Astro, and a pre-ship checklist

mzizi-language and mzizi-roots are new in 0.8.0. The React (TSX) build of the components is the deprioritised secondary in every skill that mentions it.

Renamed and removed skills

Breaking in 0.8.0: the nine 0.7.0 skills became five, with no aliases. Anything that loads a skill by an old name (mzizi_get_skills, GET /v1/skills/<name>, skills/<name>/SKILL.md, a plugin command) must switch to the new name. An old name answers 404 on api.mzizi.dev/v1/skills/<name>.

The owner’s decision of 30 September 2026 was fewer skills that are effective rather than many that are not. Where each 0.7.0 skill went, from the bundle’s README:

`0.7.0` skill	From `0.8.0`
`scaffold-component`	`mzizi-roots`, “Contributing a component”
`simplify`	`mzizi-roots`, “Reuse before build”
`ecosystem-app-setup`	`mzizi-roots`, “Starting an app”, and `mzizi-design`, “What belongs in the ecosystem”
`nyuchi-design`	`mzizi-design`, “The design system”; `tokens-update.css` moved with it
`cloudflare-worker-rust`	`mzizi-backend`, “A Rust Worker”
`mcp-server-cloudflare`	`mzizi-backend`, “An MCP server”
`mukoko-design`	Removed. Its generated `tokens/*` files moved to `mzizi-design/tokens/`; the mukoko brand assets move to a Nyuchi bundle
`mzizi-design`	Kept, and absorbs the design half of the rest
`discoverability`	Kept

mzizi-design was called bundu-design before 0.6.0.

Getting the skills

Four ways, serving the same bundle once each has caught up. On 30 September 2026 all four (npm, the MCP server, the API and the plugin) served 0.8.5; each says which version it serves. All carry the same five skills.

From npm

npm install -D @nyuchi/mzizi-skills
npx skills experimental_sync          # links the bundled skills into .agents/skills/

npx skills add @nyuchi/mzizi-skills does not work: the skills CLI reads that argument as a GitHub repository and fails to clone it. experimental_sync is its route for skills shipped in node_modules.

From the MCP server

mzizi_get_skills on the MCP server lists the skills, or returns one in full. It is free, with no sign-in and nothing to install. Each skill’s source names where it is authored, mzizi-dev/agent-tools/mzizi-skills/skills/<name>, from mzizi-mcp 0.11.1.

From the API

GET https://api.mzizi.dev/v1/skills lists them, and GET /v1/skills/<name> returns one. GET /v1/skills/summary is the cheap way to check which version a surface is serving: its meta carries version and count.

As a Claude Code plugin

The public mzizi plugin carries the five skills and connects the Mzizi MCP server:

/plugin marketplace add mzizi-dev/mzizi-registry
/plugin install mzizi@mzizi

It lives in the plugin/ directory of mzizi-dev/mzizi-registry, which holds a byte-for-byte copy of the bundle’s skills/, and its manifest points the MCP connection at https://mcp.mzizi.dev/mcp.

The plugin and the mzizi-tools marketplace that used to live in the private tooling repository are retired. If you installed them, remove them with /plugin uninstall mzizi@mzizi-tools and /plugin marketplace remove mzizi-tools, then install the public plugin above.

How each copy stays current

Copy	Where it gets the bundle
npm	Published from the bundle’s source on every merge that bumps its version
`mzizi_get_skills`	The MCP server bundles the skills from the same source when it is built
`api.mzizi.dev/v1/skills`	The registry depends on the npm package and inlines it at build time; the gateway serves a pinned registry commit
The plugin	The registry’s `plugin/skills/`, regenerated from the npm package it depends on

The API and the plugin can lag the newest npm release: a release reaches them only when the registry’s dependency is bumped and, for the API, the gateway is re-pinned. Check the versions rather than assuming they agree.

Git is the source of truth

Skills are authored as skills/<name>/SKILL.md, with YAML frontmatter carrying name and description, and listed in an index.json. That bundle is the only home for skill content. There is no database copy and no sync step. The registry and the MCP server each inline the bundle at build time, so bumping the bundle version is a commit, and the commit is what changes what agents read. An older model projected skills into a database table with a sync script; that is gone.

Never edit a skill anywhere but the bundle. Not a copy vendored into a consumer repository, not the plugin’s copy, and not a .claude/skills/*.md file. The next regeneration overwrites them.

Changing a skill

The bundle is built in the private tooling repository, so outside contributors cannot open a pull request against it directly. Report a problem with a skill through the registry’s issue tracker, mzizi-dev/mzizi-registry. For maintainers, the rules the bundle’s own gate enforces:

Edit skills/<name>/SKILL.md. Adding a skill also needs an index.json entry, because consumers read the index and an unlisted skill is invisible.
Bump the version in both package.json and index.json; they move together. Any change to skill text needs a bump, so npm and mzizi_get_skills stay on the same version.
The offline validator checks the version, the index, the frontmatter and the exports map before publish, and needs no credentials.
A merge without a version bump publishes nothing.
Then bump the bundle version the registry depends on, and regenerate its skills and the plugin’s copy, so the API and the plugin serve it. The MCP server builds its copy from the same repository as the bundle, so it picks the change up on its next deploy.

​Renamed and removed skills

​Getting the skills

​From npm

​From the MCP server

​From the API

​As a Claude Code plugin

​How each copy stays current

​Git is the source of truth

​Changing a skill

Renamed and removed skills

Getting the skills

From npm

From the MCP server

From the API

As a Claude Code plugin

How each copy stays current

Git is the source of truth

Changing a skill