Summary
Add optional metadata frontmatter fields (purpose, task, audience) that help agents orient themselves before reading a bundle or concept file. These fields provide lightweight context about why a knowledge bundle exists, what agent task produced it, and who should consume it — without requiring new type values or a taxonomy registry.
Motivation
OKF models domain knowledge: what the world knows about a subject. But the same format is increasingly used to document what an agent accomplished as proof of work that downstream agents need to validate. A bundle of domain concepts cannot easily serve as a task deliverable because the concepts describe what is true, not what an agent discovered or decided.
OKF's unregistered type field is one of its best features. Adding required type values (like type: Analysis or type: Discovery) would create the governance problem OKF wisely avoids. Instead, producers should add metadata hints that help an agent decide whether to read before parsing.
Proposal
Add the following optional frontmatter fields to the recommended list:
purpose: <short description of why this bundle or concept exists>
task: <name or description of the agent task that produced this content>
audience: <intended consumer role, e.g., "product-manager", "data-engineer">
All three are OPTIONAL. None require a spec change. They are hints, not enforcement. Consumers that do not understand them ignore them. Consumers that do understand them can route more intelligently.
The description field already exists in OKF v0.1 frontmatter and serves a similar orientation function at the concept level. The Agent Skills format (agentskills.io) uses a description field in exactly this way: a short string that tells an agent whether to load more. This proposal extends that pattern to the bundle level and adds task/audience context.
Relationship to Spec
Backward-compatible addition to the recommended frontmatter fields. OKF already permits arbitrary additional keys. This formalizes a naming convention for commonly useful orientation metadata.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)
Summary
Add optional metadata frontmatter fields (
purpose,task,audience) that help agents orient themselves before reading a bundle or concept file. These fields provide lightweight context about why a knowledge bundle exists, what agent task produced it, and who should consume it — without requiring new type values or a taxonomy registry.Motivation
OKF models domain knowledge: what the world knows about a subject. But the same format is increasingly used to document what an agent accomplished as proof of work that downstream agents need to validate. A bundle of domain concepts cannot easily serve as a task deliverable because the concepts describe what is true, not what an agent discovered or decided.
OKF's unregistered
typefield is one of its best features. Adding required type values (liketype: Analysisortype: Discovery) would create the governance problem OKF wisely avoids. Instead, producers should add metadata hints that help an agent decide whether to read before parsing.Proposal
Add the following optional frontmatter fields to the recommended list:
All three are OPTIONAL. None require a spec change. They are hints, not enforcement. Consumers that do not understand them ignore them. Consumers that do understand them can route more intelligently.
The
descriptionfield already exists in OKF v0.1 frontmatter and serves a similar orientation function at the concept level. The Agent Skills format (agentskills.io) uses adescriptionfield in exactly this way: a short string that tells an agent whether to load more. This proposal extends that pattern to the bundle level and adds task/audience context.Relationship to Spec
Backward-compatible addition to the recommended frontmatter fields. OKF already permits arbitrary additional keys. This formalizes a naming convention for commonly useful orientation metadata.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)