biome

# BIOME — Mother Skill for Platform Descriptors > **BIOME** *n.* — a bounded region of an ecosystem, with its own inhabitants and climate, **coexisting** with sister biomes and **exchanging** matter, energy, and information with them along defined gateways. This skill is the **mother prototype** that platform-descriptor sister skills inherit from. Each daughter biome declares `inherits: biome` in its CARD.yml / GLANCE.yml / SKILL.md frontmatter, and its directory structure mirrors the skeleton this skill defines. **Six example biomes ship with this skill** for reference, each illustrating a distinct dimension: | Biome | Family | What it exemplifies | |---|---|---| | [`biomes/gcp/`](biomes/gcp/) | cloud | Canonical cloud hyperscaler | | [`biomes/aws/`](biomes/aws/) | cloud | Another hyperscaler with distinct vocabulary (accounts, regions, AZs, SSO) | | [`biomes/azure/`](biomes/azure/) | cloud | A third hyperscaler with enterprise-IT flavor (subscriptions, RGs, Managed Identities) | | [`biomes/github/`](biomes/github/) | collaboration | **Cross-cutting** — forge + CI + social graph + MMPORG + branch-as-object database; touches every other biome | | [`biomes/tailscale/`](biomes/tailscale/) | overlay | **Cross-cutting** — mesh network that threads through every other biome by design | | [`biomes/cloudflare/`](biomes/cloudflare/) | overlay | **Multi-role** — CDN + Workers + R2 + DNS + Tunnels + Pages; the "many simultaneous roles" lesson | Consumer repos adopt this skill and populate their own `biomes/registry.yml` + `biomes/gateways.yml` + per-biome daughter skills in their own repos. The example biomes here are vendor-neutral reference material, not a working registry. ## Why "biome" — not "microworld," "virtual world," or "platform" The name is deliberate. The ecological framing does three things no other candidate does: - **Microworld** (Papert's term, MOOLLM's ambient usage) implies an *isolated* space — a pedagogical sandbox sealed against distraction. A MOOLLM microworld is single-subject by design. Biomes are explicitly **not isolated** — inhabitants cross boundaries; a cloud MIG pulls images from the github biome; an edge box pulls models from a cloud biome; tailscale threads SSH through all of them at once. Isolation is the wrong shape. - **Macroworld / virtual world** implies *simulation* or *containment*. Biomes are **real operational territory** — they aren't modeled, they're inhabited. Machines run there, bills come from there, outages happen there. - **Platform** is accurate but flat. "Platform" hides that there's weather, seasons, predators, migrations — that things live in these places, have needs, interact. The platform-language invites thinking of GCP and Azure as interchangeable slots. The biome-language makes it obvious that the Amazon is not the Sahara is not a coral reef, even if they all "have climate and elevation." The ecology metaphor earns its keep when you start looking at cross-biome flows: - **Exchange** — containers built in github, consumed by cloud VMs; videos produced at edge boxes, flowing up to cloud buckets; models trained somewhere, distributed everywhere. - **Symbiosis** — tailscale overlays every biome without owning any of them; a devops meta-biome serves images to every biome and exists for no other purpose. - **Migration** — workloads move (GPU SKU upgrades; cross-cloud parity rollouts). - **Climate** — each biome has its own rate constants: cloud MIG autoscaler cooldowns, edge spot preemption rates, CI runner queue times. - **Niches** — each biome supports workloads the others can't (or won't): edge runs local because it has to, cloud runs pay-per-use because it can, forges run CI because they already have the code. All of these are captured structurally by the skeleton (recipes/instances/runbooks/gotchas/...) and by the consumer repo's `biomes/gateways.yml`, which is the explicit record of cross-biome exchange. **Gateways are not a metadata afterthought — they're the biological substance of the ecosystem.** > **Structural ancestry.** This pattern is directly modeled on MOOLLM's [`schema` skill (schemapedia)](../schema/). Schemapedia maintains a registry of schema mechanisms (json-schema, sqlite, git, drescher, …) with [`registry.yml`](../schema/schemas/registry.yml) + [`plugin-convention.yml`](../schema/schemas/plugin-convention.yml) + [`gateways.yml`](../schema/schemas/gateways.yml). The biome pattern applies the same idea one level up — each biome is a **full sister skill** rather than a plugin entry inside a single skill, but the registry / convention / gateways triad is deliberately parallel. See [`biomes/convention.yml`](biomes/convention.yml) and [`biomes/families.yml`](biomes/families.yml). ## Inheritance, the Self way Each daughter biome is an **instance** of the biome prototype: ```yaml # In skills/gcs/CARD.yml (and GLANCE.yml) inherits: - biome ``` When a daughter biome doesn't define a convention locally, the answer lives here — first-match-wins delegation per MOOLLM's [Delegation Object Protocol (DOP)](../skill/delegation-object-protocol.md). When you land in a daughter biome and the question is "what does this skeleton mean?", consult this skill. ## Why a shared skeleton - **Predictable navigation.** Once you know where to find gotchas in one biome, you know where to find them in any biome. - **Low-friction expansion.** New biomes (runner, tailscale, future platforms) grow into the skeleton instead of inventing their own. - **Cross-biome learning.** Lessons from one biome (e.g., "GCP has invisible quota for new accelerator families") find their parallels in another (e.g., "Azure has 0-default quota for new VM families") because both live at the same path. - **MOOLLM alignment.** Each biome is a microworld — a bounded, coherent space where platform-specific vocabulary and patterns make sense. The skeleton is the shared grammar. ## What makes a biome A MOOLLM-compatible platform biome is a directory under `skills/` that describes **one operational platform** — a place where you run workloads (cloud VMs, on-prem hardware, CI runners), a registry or image source (Artifact Registry, Docker Hub, a private package index), an identity or network plane you depend on (Tailscale, Cloudflare, Firebase), or any other bounded infrastructure surface whose specific vocabulary and quirks are worth capturing. Not every skill is a biome. A biome is specifically a **platform descriptor** — it encodes operational knowledge of a bounded infrastructure surface. Non-biome skills include process skills, workload skills, and meta-skills (e.g., `skill`, `card`, `cauldron`, `schema`, `file-system-object`). A biome declares membership by inheriting from this skill. ## Core files (required — the Semantic Image Pyramid) Every biome must declare these: | File | Purpose | Typical size | |---|---|---| | `GLANCE.yml` | Quick scan: what, why, when, methods, key gotchas, key files, sister skills, **`inherits: biome`** | 50-100 lines | | `CARD.yml` | Sniffable interface: activation k-lines, advertisements, methods, state, files index, navigation, **`inherits: [biome]`** | 150-300 lines | | `SKILL.md` | Protocol overview, core mental model, worked examples, documentation map | 300-500 lines | | `README.md` | Human landing page with reading order and quick links | 50-80 lines | ## Core subdirectories (standard skeleton) Every biome should have these directories, even if initially populated only by a `README.md` stub. They fill in over time as we learn. | Directory | Contents | Reading convention | |---|---|---| | `recipes/` | Ready-to-run commands and short patterns. Markdown files organized by task theme. The "bash snippet you Google for at 2am" section. | `recipes/<topic>.md`; plus `recipes/README.md` as index | | `instances/` | Per-deployment knowledge cache. One subdir per deployed instance (project, subscription, on-prem box). Contains `state.yml`, `history.md`, per-instance `deploy.md` where useful. | `instances/<name>/README.md` | | `runbooks/` | Task-oriented walkthroughs. Each runbook covers one multi-step operation end-to-end. | `runbooks/<UPPERCASE-TASK>.md` | | `gotchas/` | Known failure modes, one per file. Each includes the symptom, the root cause, and the fix. The archive of "this took a deploy cycle to figure out." | `gotchas/<kebab-case-symptom>.md` | | `protocols/` | Deep documentation of mechanisms and invariants. Longer-form than recipes, more stable than gotchas. | `protocols/<topic>.md` | | `scripts/` | Automation hooks specific to this biome (probes, diagnostic wrappers). Not user-facing CLIs (those live in `tools/`). | `scripts/<name>.sh` | | `cost/` | Date-stamped billing analyses. Each file captures a specific finding with the queries, raw numbers, interpretation, and action. | `cost/YYYY-MM-DD-topic.md` | ## Cloud-biome-specific subdirectories For biomes whose platform is a public cloud (`gcs`, `azure`, future `aws`): | Directory | Contents | |---|---| | `quota/` | Quota inventory per region/family. What we have, what we've requested, what's blocking. | | `regions/` | Region/zone/SKU availability catalogs. "Where does our fleet run, and why." | ## Edge-biome-specific subdirectories For `edgebox` (and any future terrestrial biomes like `customer-hardware`): | Directory | Contents | |---|---| | `stacks/` | Stack types (vision, builder, training). A biome-specific concept — an edgebox can be deployed as different stack shapes; a GCS project can't. | | `templates/` | Template files for new instances. | ## CLI tool ecosystem (optional but encouraged) Every biome operates through a set of command-line tools — `gcloud` for GCP, `az` for Azure, `aws` for AWS, `ssh`/`docker`/`systemctl` for edge/on-prem, `gh`/`git` for forges, `tailscale` for mesh network, `wrangler`/`flarectl` for Cloudflare. The biome's CARD.yml should list them in a `cli_tools:` block so newcomers (and LLMs) can tell at a glance "which binary do I invoke for which concern." Minimal shape (see [`biomes/convention.yml`](biomes/convention.yml) for the full spec): ```yaml cli_tools: - name: gcloud role: "GCP CLI for compute, secrets, IAM, pubsub, etc." install: "brew install --cask google-cloud-sdk" auth: "gcloud auth login --no-launch-browser" primary_usage: "recipes/gcloud-patterns.md" vendor_docs: https://cloud.google.com/sdk/gcloud - name: gsutil role: "GCS object storage CLI (bucket listings, cp/mv, lifecycle)" primary_usage: "bucket reads/writes, syncing artifacts" also_used_by: [edge-on-prem] # shared CLI → record as a gateway ``` Tools used across multiple biomes (`docker`, `git`, `ssh`, `gsutil`, `tailscale`) should be listed in every biome that uses them AND get a corresponding bridge entry in the consumer repo's `biomes/gateways.yml` with `kind: shared_cli_tool`. ## Optional / grows-as-needed | Directory | When | |---|---| | `examples/` | Free-form examples not fitting into recipes/runbooks. | | `benchmarks/` | Performance data captured over time. | | `designs/` | Design intent docs specific to this biome. | | `snapshots/` | Point-in-time captures (state exports, probe output). | ## The skeleton, visualized ``` skills/<biome>/ ├── GLANCE.yml # 👁️ required (Semantic Image Pyramid) ├── CARD.yml # 📇 required, declares inherits: [biome] ├── SKILL.md # 📜 required, declares inherits: [biome] in frontmatter ├── README.md # 📚 required │ ├── recipes/ # Ready-to-run commands │ └── README.md # index │ ├── instances/ # Per-deployment knowledge │ └── README.md │ ├── runbooks/ # End-to-end walkthroughs │ └── README.md │ ├── gotchas/ # Known failure modes │ └── README.md │ ├── protocols/ # Deep documentation │ └── README.md │ ├── scripts/ # Biome-specific automation │ └── README.md │ ├── cost/ # Date-stamped billing analyses │ └── README.md │ ├── quota/ # Cloud biomes only │ └── README.md │ ├── regions/ # Cloud biomes only │ └── README.md │ └── stacks/ # Edge biomes only └── README.md ``` Use [`templates/BIOME/`](templates/BIOME/) as the directory scaffold to instantiate from when adding a new biome. ## When to promote content into the skeleton Content lives in one of three places: 1. **SKILL.md** — the canonical overview, everything cross-referenced. 2. **Subdirectory file** — when a topic grows beyond 1-2 paragraphs in SKILL.md, or when it has its own lifecycle (date-stamped cost analyses, per-instance state, gotchas with distinct identity). 3. **External doc** (under a repo-level `docs/` path or a sibling skill) — when the topic spans multiple biomes or is cross-cutting (e.g., a `cloud-gpu-platforms.md` that catalogs GCP + Azure + AWS GPU SKUs side-by-side). The skeleton establishes where things *can* live. Movement is lazy: keep it in SKILL.md until it earns its own file by being longer than a paragraph or having an independent lifecycle. ## Example biomes shipped with this skill | Biome | Family | Emoji | What it illustrates | |---|---|---|---| | [`biomes/gcp/`](biomes/gcp/) | cloud | ☁️ | Canonical cloud hyperscaler; recipes/regions/quota/cost shapes | | [`biomes/aws/`](biomes/aws/) | cloud | ☁️ | Hyperscaler with distinct vocabulary (accounts, AZs, IAM, SSO) | | [`biomes/azure/`](biomes/azure/) | cloud | ☁️ | Hyperscaler with enterprise-IT flavor (subscriptions, RGs, MI) | | [`biomes/github/`](biomes/github/) | collaboration / cross-cutting | 🐙 | Forge + CI + social graph + branch-as-object store; touches every other biome | | [`biomes/tailscale/`](biomes/tailscale/) | overlay / cross-cutting | 🕸️ | Mesh overlay that threads through every biome by design | | [`biomes/cloudflare/`](biomes/cloudflare/) | overlay / multi-role | ☁️✈️ | CDN + Workers + R2 + DNS + Tunnels + Pages; one brand, many roles | Each of these is a **stub** with the minimal skeleton (`GLANCE.yml`, `CARD.yml`, `README.md`, and a seed `README.md` per required subdirectory). Consumer repos are expected to either: - (a) fork the stub into their own `skills/<biome>/` and grow it with site-specific recipes/instances/gotchas, declaring `inherits: biome`; or - (b) leave the stub as-is in `moollm/` and write a thin consumer-side overlay skill that inherits from it (same `inherits: biome` chain, plus `inherits: biome.<biome-name>` for delegation into the stub's CLI tool list / vendor doc links). ## Candidate future example biomes Platforms common enough to deserve a reference stub when someone authors one: | Candidate | Nature | Why it matters | |---|---|---| | `firebase` | Auth / realtime DB / hosting | Multi-role like Cloudflare; auth plane crosses every biome that consumes identity | | `postgres` | Database | Spans managed (RDS/Cloud SQL/Azure DB) + self-hosted; worth documenting both | | `bigquery` | Data analytics | Cloud data-warehouse shape; sister to Snowflake/Redshift | | `kubernetes` | Orchestrator-as-platform | When consumer fleets include k8s; distinct enough to deserve its own biome | | `terraform` | IaC | Cross-cutting like github — every biome consumes it | | `1password` / `vault` | Secrets plane | Identity-adjacent overlay biomes | New example biomes become worth shipping when they illustrate a **distinct biome shape** (new family, new cross-cutting pattern, new failure-mode cluster) — not just another cloud vendor. ## Parallel to schemapedia — which files do what Schemapedia and biome-pedia both split responsibility across a registry / convention / gateways triad. Side-by-side: | Concept | Schemapedia (`skills/schema/`) | Biome (this skill, `skills/biome/`) | |---|---|---| | **Convention** | [`schemas/plugin-convention.yml`](../schema/schemas/plugin-convention.yml) | [`biomes/convention.yml`](biomes/convention.yml) (machine-readable) + this `SKILL.md` (prose) | | **Registry** | [`schemas/registry.yml`](../schema/schemas/registry.yml) | Consumer repo's `biomes/registry.yml` (this skill ships example biomes, not a working registry) |