DEV Community

Cover image for Open Knowledge Format (OKF) vs Agent Skills
Dmitrii
Dmitrii

Posted on • Originally published at quotyai.com

Open Knowledge Format (OKF) vs Agent Skills

#ai #agentskills #opensource

Two Standards for AI Agent Knowledge - and Why Both Fall Short

We have two open standards for defining AI agent knowledge: Google's Open Knowledge Format (OKF) and Anthropic's Agent Skills. Before adopting either, it's crucial to understand their fundamental architectural differences.

At QuotyAI, building production agentic systems has taught us that how you structure knowledge is a major architectural bet. Here's a breakdown of both standards, where they break at scale, and why you might want to skip static files altogether.

The Problem: How Does the Model Know You Data?

We mentioned it before: schema for AI is important!.

But a foundation model knows nothing about your orders table. It doesn't know that confirmed_at is the right timestamp for revenue reporting. It doesn't know your metric definitions or internal APIs. Someone has to tell it.

open-knowledge-format-vs-agent-skills

What OKF Actually Does

Core idea: with OKF you use external tools to traverse the knowledge graph and give it to AI.

OKF is a directory of Markdown files. Each file represents one concept — a table, a metric, an API.

---
type: table
title: orders
resource: bigquery://my-project.ecommerce.orders
---

Primary key: `order_id`. Joins to `customers` on `customer_id`.
Use `confirmed_at` for revenue reporting — not `created_at`.
Enter fullscreen mode Exit fullscreen mode

How agents consume it: The external orchestrator explicitly decides what to fetch. An agent might call a tool that queries the bundle by type or keyword. The selection logic lives in your code, not the format.

**OKF **allows you to visualize the graph and display a strict schema:
OKF Graph

What Agent Skills Actually Does

A Skill is a folder containing a SKILL.md plus any supporting files.

---
name: orders-schema
description: >
  Use when the task involves querying, analyzing, or joining the orders table,
  including revenue calculations.
---

Table location: `bigquery://my-project.ecommerce.orders`
For revenue: use `confirmed_at`, not `created_at`.
Enter fullscreen mode Exit fullscreen mode

How agents consume it: Claude reads the description field and probabilistically decides whether to load the full skill into its context based on the current task. This happens automatically (via view tool calling) - no orchestration code required.

What's Missing: Strict Contracts and Determinism

At QuotyAI, we realized early on that an AI agent is only as reliable as its runtime constraints. Both OKF and Skills fail to provide these constraints.

What's Missing From Skills: Typed Contracts
Skills need more than a description field and a Markdown body. They lack what we call typed skill contracts:

  • No type system: A skill documenting a schema looks identical to one defining a multi-step workflow. There's no type: knowledge or type: procedure.
  • No input/output contracts: A "generate SQL query" skill might assume a table name and output format, but Claude infers it from prose. There's no structured schema enforcing what goes in and what comes out.
  • No failure boundaries: If a skill fails, it fails ambiguously. There's no defined set of error codes (SLOT_UNAVAILABLE, CUSTOMER_NOT_FOUND) that a deterministic fallback path can catch.

What's Missing From OKF: Agent Execution Hooks
OKF describes a knowledge graph, but doesn't give agents an executable map through it.

  • Concepts are passive: An orders table concept doesn't tell the agent to "fetch revenue.md before writing any query." The agent receives a concept and probabilistically decides what to do next.
  • No design-time vs runtime separation: OKF files are a design-time artifact, but agents need runtime reasoning. A file doesn't provide a deterministic test runner or an interpreter to validate if the agent actually understood the concept.

When to Use Each Today

Despite their gaps, both formats are usable now if you pick the right scope.

  • Use OKF when: You have 150+ collections and want to have a single entrypoint to analyze them.
  • Use Skills when: Chatbot is your primary runtime and you have small, focused workflows needing automatic trigger-based activation.
  • Use Deterministic Code Execution for everything else: For anything mechanical — "what does the live system look like right now?" — query the truth at runtime instead of reading a static file about it.

Top comments (0)