@nyuchi/mzizi-skills

The npm-distributable agent-skills bundle for the mzizi ecosystem.

The repo is the source of truth. Skills are authored in-repo under mzizi-skills/skills/<name>/SKILL.md (plus any assets the skill ships) and listed in index.json. A skill's SKILL.md may still reference the live nyuchi_design_db for volatile token values, but the skill document itself is owned by this repo.

Install

npx skills add @nyuchi/mzizi-skills

Or install the whole toolchain as a Claude Code plugin — these skills, the fundi agent, the registry MCP, and the /mzizi:* commands in one step:

/plugin marketplace add nyuchi/mzizi-tools
/plugin install mzizi@mzizi-tools

Current skills

Design and brand

| Name | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | bundu-design | Ecosystem-level brand: the bundu parent identity, brand constellation, Ubuntu pillars. Use for cross-brand materials and brand-voice decisions. | | nyuchi-design | UI and tokens: Seven African Minerals colour system, radius scale, type stack (Noto Sans/Serif + JetBrains Mono), pill-button rules, super-app UI kit. | | mukoko-design | mukoko brand identity: the seven-mineral Seed-of-Life Swarm mark, full mineral palette, SVG/PNG assets, and design tokens. |

Engineering doctrine

| Name | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | simplify | Reuse before build, styles as N1 tokens, compose pages from N2/N3, collapse duplication into CVA variants, delete-first. Companion to the get_simplify_guidance MCP tool. | | discoverability | SEO + AIO: link previews, the brand-agnostic hive OG-image template, Next.js + Astro/Starlight wiring, and a pre-ship checklist. | | scaffold-component | Authoring a new component into the component_documents store — picking the node, the per-node criteria checklists, docs/demos, alpha→stable. | | ecosystem-app-setup | Bootstrapping a new bundu-ecosystem app: Next.js, token wiring, components.json against the registry, theme provider, fundi, Ubuntu constraints. | | cloudflare-worker-rust | The workers-rs house pattern — layout, wrangler config, cron/queue, Supabase access, auth by audience — and when Rust beats the TS stack. | | mcp-server-cloudflare | Adding an MCP Worker: the live endpoint map, one-factory/many-entrypoints, registry-driven catalogues with drift gates, and MCP-registry publish. |

Consumers

• @nyuchi/mzizi-cli (fundi agent) — bundles this package and reads it offline via loadMziziSkills().
• The mzizi Claude plugin — symlinks skills/ so there is one source of truth.
• AI assistants in consumer projects — install via npx skills add @nyuchi/mzizi-skills.
• The Mzizi registry — the same bodies are served at mzizi.dev/api/v1/skills/{name} and over the MCP (get_skill), projected from this bundle by pnpm skills:sync.

Authoring a skill

1. Add a directory under mzizi-skills/skills/, e.g. skills/my-skill/.

2. Write skills/my-skill/SKILL.md with YAML frontmatter containing name and description:

   ---
   name: my-skill
   description: One-line description consumed by loadMziziSkills().
   ---
   <!-- skill body -->

3. Add an entry to index.json (name, file, description):

   {
     "name": "my-skill",
     "file": "skills/my-skill/SKILL.md",
     "description": "One-line description."
   }

4. Bump the @nyuchi/mzizi-skills version in both package.json and index.json — they move in lockstep and the validator fails on drift.

5. Run the gate from the repo root:

   pnpm skills:validate

package.json#exports must expose ./index.json and ./skills/* or the SDK's loadMziziSkills() falls back to its built-in defaults.

Publishing

Publishing is automatic: merging a change under mzizi-skills/ to main runs .github/workflows/publish-mzizi-skills.yml, which validates the bundle and publishes to npm with provenance. The workflow checks the npm registry first, so a merge that doesn't bump the version is a no-op — bump the version or nothing ships.

Syncing into the DB

Git is the source of truth for skill content, but the live mzizi-mcp / registry surface also serves skills out of a Supabase skills collection. The repo-root scripts/sync-skills.mjs script projects this bundle (frontmatter-stripped SKILL.md body + description) into that collection — disk → DB, the write-direction twin of the nyuchi/mzizi repo's sync-tokens.ts:

pnpm skills:sync    # upsert every bundled skill into the DB (needs a service-role key)
pnpm skills:check   # CI gate — fails if the DB has drifted from the committed SKILL.md files

See CLAUDE.md §8 in the repo root for the full contract (which fields are git-owned vs. DB-managed).

License

Apache-2.0. Governed by the Bundu Foundation.