Imported from zoickx/dotfiles (agents/.rulesync/skills/okf/SKILL.md). Install upstream with npx skills add zoickx/dotfiles --skill okf. Copyright stays with the author.

OKF

Use this skill to work with Open Knowledge Format (OKF) v0.1 draft bundles. Treat an OKF bundle as a self-contained, human-readable and agent-readable directory tree of Markdown files with YAML frontmatter.

Prefer simple files over tooling. If you can read Markdown, parse YAML frontmatter, and traverse directories, you can work with OKF.

Operating Model

• Treat the knowledge bundle as the unit of distribution.
• Treat each non-reserved .md file as one concept.
• Treat a concept's ID as its path within the bundle without the .md suffix.
• Use standard Markdown links to express relationships.
• Preserve unknown frontmatter keys when editing.
• Tolerate partial knowledge: missing optional fields, unknown types, unknown extra fields, broken links, and missing indexes are allowed for consumers.
• Keep authoring minimal and explicit. Do not invent registries, schemas, SDKs, or hidden metadata stores.

Bundle Structure

Create or inspect a bundle as a directory tree of Markdown files:

path/to/bundle/
├── index.md
├── log.md
├── <concept>.md
└── <group>/
    ├── index.md
    ├── <concept>.md
    └── <subgroup>/
        └── ...

• Use a git repository when possible. Git gives history, attribution, and diffs.
• Allow a bundle to also be a zip, tarball, or subdirectory in a larger repository.
• Organize directories by the producer's domain. OKF does not define a fixed taxonomy.
• Reserve index.md and log.md at every directory level.
• Do not use index.md or log.md as concept documents.
• Treat all other .md files as concept documents.

Concept Documents

Write every concept document as UTF-8 Markdown with:

1. A YAML frontmatter block at the top, delimited by --- lines.
2. A Markdown body after the frontmatter.

Use this shape:

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column | Type | Description |
|---|---|---|
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | Foreign key into [customers](/tables/customers.md). |

# Citations

[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

Required Frontmatter

• Add type to every concept document.
• Make type a non-empty, descriptive string.
• Use type values such as BigQuery Table, BigQuery Dataset, API Endpoint, Metric, Playbook, or Reference when appropriate.
• Do not rely on central registration. Consumers must tolerate unknown types.

Recommended Frontmatter

Add these fields when the information is known:

• title: Human-readable display name. Consumers may derive it from the filename if absent.
• description: One sentence summary for indexes, search snippets, and previews.
• resource: URI for the asset the concept describes. Omit it for abstract concepts.
• tags: YAML list of short strings for cross-cutting categorization.
• timestamp: ISO 8601 datetime for the last meaningful change.

Extension Frontmatter

• Add producer-defined keys when useful.
• Preserve unknown keys when round-tripping files.
• Do not reject a document because it has unrecognized keys.

Body Conventions

Use standard Markdown. Favor structural Markdown over long prose:

• Use headings.
• Use lists.
• Use tables.
• Use fenced code blocks for examples and snippets.

There are no required body sections. Use these conventional headings when applicable:

• # Schema: Describe columns, fields, or structured assets.
• # Examples: Provide concrete usage examples.
• # Citations: List sources backing claims in the body.

Cross-Links

Use standard Markdown links between concepts.

Prefer absolute bundle-relative links:

See the [customers table](/tables/customers.md).

Use relative links when they are clearer in local context:

See the [neighboring concept](./other.md).

Interpret links this way:

• A link from concept A to concept B asserts a relationship.
• The surrounding prose defines the relationship type.
• Do not encode a global link taxonomy into OKF.
• Consumers that build graphs usually treat links as directed, untyped edges.
• Consumers must tolerate broken links. A broken link is not malformed OKF.

Index Files

Use index.md to support progressive disclosure in any directory, including the bundle root.

In ordinary directory indexes:

• Do not add frontmatter.
• Group links under headings.
• Include the linked concept's description when available.
• Link subdirectories when that helps traversal.
• Generate indexes automatically when useful.
• Synthesize indexes at consumption time if they are missing.

Use this shape:

# Tables

* [Orders](orders.md) - One row per completed customer order.
* [Customers](customers.md) - One row per customer account.

# Playbooks

* [Freshness Alert](playbooks/freshness-alert.md) - Triage steps for freshness alerts.

Version exception:

• A bundle-root index.md may declare the targeted OKF version with frontmatter.
• This is the only place frontmatter is permitted in an index.md.
• Use okf_version: "0.1" when declaring the version.

---
okf_version: "0.1"
---

# Bundle Index

* [Tables](tables/) - Data warehouse table concepts.

Log Files

Use log.md to record chronological updates for the directory scope.

• Place log.md at any directory level where history is useful.
• List entries newest first.
• Use ISO 8601 YYYY-MM-DD date headings.
• Treat bold labels such as **Update**, **Creation**, and **Deprecation** as conventions.

Use this shape:

# Directory Update Log

## 2026-05-22

* **Update**: Added [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).

## 2026-05-15

* **Initialization**: Created foundational directory structure.

Citations

When a concept body makes sourced claims, add a # Citations section at the bottom.

• Number citations.
• Use absolute URLs, bundle-relative paths, or paths into a references/ subdirectory.
• Mirror external material as first-class OKF concepts when that improves portability.

Use this shape:

# Citations

[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
[2] [Internal data quality runbook](https://wiki.example.internal/data/quality)

Authoring Workflow

When creating or expanding an OKF bundle:

1. Choose the bundle root.
2. Create directories that match the producer's domain.
3. Create one concept document per knowledge unit.
4. Add required type frontmatter to every concept.
5. Add recommended frontmatter when known.
6. Use structural Markdown in the body.
7. Add bundle-relative links between related concepts.
8. Add citations for sourced claims.
9. Add or refresh index.md files for discoverability.
10. Add or refresh log.md files when update history matters.
11. Validate conformance before finishing.

Consumption Workflow

When reading an OKF bundle:

1. Locate the bundle root.
2. Read the root index.md first if present.
3. Traverse index.md files before opening individual concepts when possible.
4. Treat every non-reserved .md file as a concept document.
5. Parse frontmatter and body separately.
6. Use type, title, description, resource, tags, and timestamp for routing and summaries.
7. Follow Markdown links to build local context.
8. Preserve and surface citations.
9. Degrade gracefully when links, indexes, optional fields, or known types are missing.

Editing Workflow

When modifying existing OKF content:

• Preserve frontmatter formatting and unknown fields.
• Preserve concept IDs unless the user asks to reorganize paths.
• Update links when moving or renaming concepts.
• Prefer absolute bundle-relative links for stability.
• Keep description to one sentence.
• Refresh timestamp only for meaningful content changes.
• Update relevant index.md entries after adding, removing, renaming, or changing descriptions.
• Add a log.md entry when the edit is material and the bundle uses logs.

Validation Checklist

Treat a bundle as conformant with OKF v0.1 only if:

• Every non-reserved .md file has parseable YAML frontmatter.
• Every concept frontmatter block has a non-empty type field.
• Every index.md, when present, follows the index structure.
• Every log.md, when present, follows the log structure with YYYY-MM-DD headings.

Do not reject a bundle for:

• Missing optional frontmatter fields.
• Unknown type values.
• Unknown additional frontmatter keys.
• Broken cross-links.
• Missing index.md files.

Minimal Example

my_bundle/
├── index.md
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md

datasets/sales.md:

---
type: BigQuery Dataset
title: Sales
description: All sales-related tables for the retail business.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
tags: [sales]
timestamp: 2026-05-28T00:00:00Z
---

The sales dataset contains transactional tables, including [orders](/tables/orders.md) and [customers](/tables/customers.md).

tables/orders.md:

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Column | Type | Description |
|---|---|---|
| `order_id` | STRING | Unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |
| `total_usd` | NUMERIC | Order total in USD. |

Part of the [sales dataset](/datasets/sales.md).