GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

v0.3 proposal: a Skill concept type with conventional shape + trust defaults

Open
#312 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Context

OKF v0.2 names some example type values but does not specify a conventional shape for **agent skill collections** — the largest producer of agent-read `.md` in the wild (SKILL.md and friends). This proposal adds one.

## What this issue is

A draft of `type: Skill` for OKF v0.3:

- **Recommended frontmatter** — `name` + `description` ("Use when…" trigger) + optional `when_to_use` / `when_not_to_use` for the activation surface
- **Recommended body sections** — `# Doctrine`, `# Algorithm`, `# Judge rubric`, `# Skip conditions`, `# Common mistakes`, `# Examples`, `# Provenance`
- **Trust family defaults for Skills** — typical `generated.by` (a developer), the two-event `verified` pattern, `sources` naming the upstreams the skill folds from, `status` defaults during the lifecycle
- **Conformance language** — what makes a `type: Skill` concept v0.3-conformant; the rule that consumers MUST NOT reject for the missing type family
- **Migration notes** — the cheapest upgrade for a methodology with plain-markdown skills

## Worked example

A generic `type: Skill` concept for an HTTP / DNS / TCP connectivity probe (`field-check`) showing the frontmatter, the trust family, and the body sections — using strictly generic vocabulary (no proprietary skills, no doctrine of any specific collection).

## Right of reply

I am happy to revise any field name, make more sections recommended, fewer sections recommended, or frame this as an informative section of the spec rather than a normative one. The proposal is a draft.

## Status of the broader submission

A worked example of OKF-bundling a real-shape methodology corpus lands as a separate PR (`samples: add a worked example — a skill collection's reference layer as an OKF bundle`) using this proposal's conventional shape as the schema by example.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing OKF v0.2's existing type-value guidance and the separate samples PR mentioned in the issue. Compare the proposed Skill frontmatter, body sections, trust defaults, conformance language, and migration notes against that baseline. Done means an agreed v0.3 proposal with a generic worked example and no unresolved schema decisions.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.