GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: Metadata orientation hints (purpose, task, audience) for agent routing
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## 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:
```yaml
purpose:
task:
audience:
```
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)
Contributor guide
Assessment
This issue has not been assessed yet.