GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
v0.3 proposal: a Skill concept type with conventional shape + trust defaults
- 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
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