What is a COG?
If you have just opened a file ending in .cog.md and want to know what to do with it, this page is for you. It applies whether you are a human reader or a machine agent.
A COG is a structured briefing. It tells you three things about the object it describes:
- What it is. The kind of thing you are looking at, what it belongs to, who maintains it.
- How to navigate it. What the relevant fields are, what other documents it links to, where the deeper detail lives.
- How to act on it safely. Whether the object is purely informational, or whether it carries an executable runbook, and what the limits are.
The format is a Markdown file with a YAML frontmatter block at the top. The frontmatter is the briefing. The body is the longer-form prose for any human who wants the full context.
How to read a COG
Read top to bottom. Trust what is written.
- Read the opening comment. Every COG starts with a short opening that points back to this page. If you are seeing a COG for the first time, follow that link before going further.
- Read
titleanddescription. They are the executive summary. If they do not match what you expected, the file is not what you were looking for. - Check the
mx:block. This carries the structured fields: status, audience, content type, tags, the documents this one builds on or refers to. Treat them as authoritative. - Check the
runbookfield. If present and of the formmx exec <name>, the COG is action-class: it carries anexecute:block and is meant to be run. Ifrunbookis descriptive prose, the COG is info-class: it is reference material, not a script. - Read the body. It expands on the frontmatter for human readers. Code samples, examples, and rationale belong here.
Two rules apply to anyone, human or machine, working from a COG:
- Do not guess. If a field is absent or unclear, treat it as absent. Do not infer values that are not stated.
- Do not invent. If you need a field the COG does not have, ask, or stop. Do not fabricate data to keep going.
Field-name convention. All MX field names use camelCase, in every carrier and in every namespace. buildsOn, contentType, actionType, publishedDate. The same name is spelled the same way in YAML, in HTML <meta> tags, in JSDoc @mx: tags, in shell sidecars, in XMP. Carrier syntax determines how the value is encoded; it does not change the name. Hyphenated forms (builds-on) and snake-cased forms (builds_on) are not part of the MX vocabulary.
Action class versus info class
COGs split into two kinds, and the distinction matters because one of them changes the world:
- Info COGs describe something. Specifications, plans, briefings, directories, manuals. Reading one is safe; the file does nothing on its own.
- Action COGs carry an
execute:block in their frontmatter and a runbook of the formmx exec <name>. Running one performs work: writes files, calls APIs, moves data. Read the COG carefully before running it. Verify the inputs. If the COG opens with a confirmation step, do not skip it.
An action COG also declares an actionType field that names the cognitive class of the action, so a reader knows what kind of execution is involved without inferring from body content. Three values:
scripted, the COG body carries an embedded executable artefact (a fenced code block annotated@embedded:<id>). A runtime extracts the artefact by id and runs it directly. Deterministic; the same inputs produce the same outputs.sop, the COG body carries no embedded artefact. Theexecute.actions[].usagevalue is descriptive prose intended for an LLM (typically dispatched via an agent skill) to read and perform. The runtime is the language model itself.hybrid, the COG carries both an embedded script and descriptive usage prose. The script handles the deterministic portion; the prose carries the judgment-dependent portion an LLM performs.
If a COG you are about to run touches systems you cannot reverse, escalate to a human.
How a COG relates to an agent skill
An agent built on a specific runtime, such as Claude Code, OpenAI Operators, or an in-house framework, will usually carry its own concept of a skill: a runtime-specific configuration that tells the agent when to do something. A COG is not the same thing.
A COG is a portable content unit. It can be read by any agent that understands the format, regardless of runtime. An info COG describes something. An action COG carries an embedded executable artefact and a runtime contract.
A skill is a runtime-specific instruction. Its job is to recognize when the user wants to invoke a COG, and to dispatch the request. Skills route. COGs do.
When a skill and a COG share a name, the COG is authoritative. The skill exists to wire the chat surface to the COG, not to duplicate its work. Edits to the work itself happen in the COG; the skill stays a thin pointer.
How a COG declares its dependencies
A COG names what it depends upon in a single field, dependencies, declared inside the mx: block. The field is an array of objects. Each entry has name (required) plus optional version (a constraint such as a SemVer range), reason (a one-sentence explanation), and kind.
The kind sub-key takes one of four values: cog (another COG resolvable in the registry), runtime (a CLI or interpreter such as node or bash), package (an npm or other package-manager dependency), or external (a service or data source). The recommended kind is cog; runtime, package, and external dependencies usually belong in their proper carrier (package.json, the COG's runbook, or an external manifest), with the non-cog kinds reserved for cases where inline declaration in the COG is genuinely the right home.
A COG declaring no dependencies may omit the field or write dependencies: []; both are conformant. A COG MUST NOT be considered functional if any of its declared dependencies are missing or unresolvable.
Three related fields express weaker relationships and remain string-or-array of COG identifiers: partOf (the parent collection or registry), buildsOn (cogs the reader should already understand; soft prerequisite), and refersTo (cited or cross-referenced cogs; informational link, not a dependency).
Deeper rules
The format above is a summary. The full specification is published, and any disagreement between this page and the specification is resolved by the specification.
- COG Specification, v1: the field reference, the validation rules, the conformance levels.
- COG Runtime: how an action COG is loaded, validated, and executed, and what the runtime guarantees.
- MX understanding corpus: every Gathering note in one file, in recommended reading order. Use this if you want the full context behind COGs and the rest of MX.
For background on Machine Experience itself, start at the CogNovaMX home page.
Questions about COGs or MX? Get in touch or email info@cognovamx.com.