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. Twelve skills in four categories, from the bundle’s index.json at version 0.20.0 (the latest on npm on 12 November 2026):

Skill	Category	What it covers
`mzizi-language`	`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), programs (`mz run`), the diagnostic codes you will meet, and what is not built yet, by the tracker’s marks
`mzizi-roots`	`build`	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 registry’s `contracts/`: the Dashboard Standard’s `app/`, the Discover Standard’s `discover/`, `site/` and `ui/`), the frontend paths (pure `.astro` from the registry with `mzizi add --target astro`, Astro with Roots, or pure Rust; Next.js adopts through the registry’s `.tsx`) and app setup, reuse before build, and contributing a component
`mzizi-design`	`design`	The design system and brand: the 21-family palette and its generated stylesheets, the radius scale, type, pill buttons, the Bundu floor (a 49px hit region and 17px body text on touch, 28px and 15px on a desktop, and 14px captions) and the spacing floor, status and surface tokens, the Dashboard and Discover Standards’ brand overlays (colour and mark only), the brand constellation, the Ubuntu pillars and principles, and the wordmarks
`mukoko-design`	`design`	mukoko’s brand files and the rules for them: the Seed of Life mark in the seven minerals, the app icon, the favicon set and the lowercase serif lockup, taken from `mukoko-news`, with `SOURCES.md` naming each file’s source and checksum. The full-palette mark is the only icon at every size, and the wordmark is always lowercase. For the palette, tokens and UI, use `mzizi-design`
`mzizi-backend`	`build`	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
`mzizi-architecture`	`build`	Where code, data and components belong, read before starting an app, site, console or page: the DNA helix (eight nodes, four rungs, six strands, read live from `api.mzizi.dev/v1/architecture`), the shell first (`AppShell` for the Dashboard Standard, `DiscoverShell` for the Discover Standard), the page patterns, and the system choices (Rust first, Astro as the default UI, Cloudflare Workers, files as the registry’s data layer, what is decided against what is built)
`discoverability`	`build`	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
`digital-hygiene`	`dev`	Disk hygiene for agents: check free disk before starting and don’t fan out below 50 GB, clone only into a folder unique to the agent and never touch another agent’s, share build caches, never commit build output, audit a clone before deleting it, and the periodic sweep. Ships `hygiene.sh` (`check`, `clone`, `audit`, `prune`, `close`, `sweep`; a dry run unless given `--apply`)
`progress-report`	`dev`	All dev work runs on a 10-minute progress-report loop: measured 20-cell bars, per-workstream state (open PRs, release, staging against main, CI, a live HTTP check), what is blocking and what is live, one “Since last report” line and “Needs you” last. Ticks are read-only. Ships `progress.sh` (`bar`, `pct`, `repo`, `lines`, `http`)
`ship-release`	`dev`	The release runbook, for when `staging` goes to `main` and the change goes live: the release branch with `staging`’s exact tree, the version rule, the merge queue, and verifying live with commands rather than trusting the merge. Ships `verify-live.sh`, which only reads
`registry-propagation`	`dev`	How a registry change reaches the products that read it, and how to tell whether it is live: the pins on `staging` (the API, the MCP server, `@bundu/ui`), the docs and site freshness checks, and the skills, with the order and what each product shows once live
`pr-gates`	`dev`	What to check before the first push of a pull request in a Mzizi repository, and the fix for each required check that keeps failing: the issue line, the changelog entry, Markdown and YAML lint, no agent-local files, formatting, CodeQL, parity and the rendered-content gates, merge methods. Never skip a test, never `--admin`

mzizi-language and mzizi-roots are new in 0.8.0, digital-hygiene in 0.9.0, progress-report in 0.10.0, mzizi-architecture in 0.14.0, mukoko-design (restored) in 0.15.0, and ship-release, registry-propagation and pr-gates in 0.18.0. 0.19.0 adds no skill: it corrects facts in the release skills and in two language and component skills. 0.20.0 adds none either: it quotes every skill’s frontmatter description, removes the curl-from-unpkg rows from the three release skills, and points them at the mzizi-dev plugin. The React (TSX) build of the components is the deprioritised secondary in every skill that mentions it.

The spacing floor

The mzizi-design skill teaches the spacing floor (14px inset, 7px gaps, 1.5 body line height), the tests that hold it and mzizi check. That change is in the bundle from 0.17.0, and 0.20.0 (the latest on npm on 12 November 2026) carries it.

Category	Skills	For
`dev`	`digital-hygiene`, `progress-report`, `ship-release`, `registry-propagation`, `pr-gates`	How every agent works, in every repository
`design`	`mzizi-design`, `mukoko-design`	The design system and brand
`language`	`mzizi-language`	Writing and checking `.mz`
`build`	`mzizi-roots`, `mzizi-backend`, `mzizi-architecture`, `discoverability`	Building components, services and sites

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, with its generated `tokens/*` files moved to `mzizi-design/tokens/`. Restored in `0.15.0`, with brand files taken from `mukoko-news`
`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; each says which version it serves. On 12 November 2026 npm, the MCP server, the API (/v1/skills/summary) and the plugins all served 0.20.0, each with all twelve skills (seven in the mzizi plugin, five in mzizi-dev). They can disagree after a release, because the API and the plugin move only when the registry’s dependency is bumped (see how each copy stays current). Connect a client says which of these each AI client can use.

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. Codex, Cursor, VS Code, Gemini CLI, Antigravity, Zed, OpenCode and Devin Desktop all read .agents/skills/, so the skills load there natively (Cline and Kiro read .cline/skills/ and .kiro/skills/ instead). Every skill’s frontmatter is only name and description, the portable core of the Agent Skills specification, from the release after 0.17.0; see the limits per client.

From the MCP server

mzizi_get_skills on the MCP server lists the skills, or returns one in full. From mzizi-mcp 0.13.0, category returns every skill in one category in full. It is free, with no sign-in and nothing to install, so any MCP client can fetch the skills this way instead of installing the npm package: Claude.ai, ChatGPT and the Claude and OpenAI APIs, which cannot install a package, included. 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

There are two plugins, both from the mzizi marketplace in mzizi-dev/mzizi-registry. The public mzizi plugin carries seven Markdown skills (mzizi-language, mzizi-roots, mzizi-design, mukoko-design, mzizi-backend, mzizi-architecture and discoverability) and connects the Mzizi MCP server. It has no scripts and no hooks, which is what the Claude plugin directory accepts without a verified organisation. The mzizi-dev plugin carries the five dev skills (digital-hygiene, progress-report, ship-release, registry-propagation and pr-gates), the shell scripts three of them ship, and the Mzizi house-rules hooks. On 12 November 2026 the manifests were at 1.10.0 (mzizi) and 0.1.0 (mzizi-dev), both naming the skills of 0.20.0:

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

The first install line is the one most people need; add mzizi-dev only to work on Mzizi’s own repositories. They live in the plugin/ and plugin-dev/ directories of mzizi-dev/mzizi-registry, which hold byte-for-byte copies of the bundle’s skills/ (the public copy leaves out one favicon the directory cannot read), and the mzizi manifest points the MCP connection at https://mcp.mzizi.dev/mcp. Codex and ChatGPT do not have the plugin yet. mzizi-registry #520 adds OpenAI’s portable manifest (plugin.json and mcp.json) beside the Claude one in plugin/, and a repo marketplace at .agents/plugins/marketplace.json. Until that reaches the registry’s main, codex plugin marketplace add mzizi-dev/mzizi-registry finds no plugin: connect the server with codex mcp add and link the skills into .agents/skills/ instead. See Connect a client.

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 plugins	The registry’s `plugin/skills/` and `plugin-dev/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.

Toolchain

The skills bundle

The spacing floor

Categories

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