GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: Metadata orientation hints (purpose, task, audience) for agent routing

Open
#96 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.