跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

okf-producer-generator

Guidance and the bundled OKF specification for building a new Open Knowledge Format (OKF) producer/connector skill in this project — the architectural principles, the okf-go library contract, the produce/ingest/schema command surface, the secret-handling and sync conventions, and the exact registration steps. Use when creating a new OKF connector or producer for a data source the project does not yet cover (e.g. MongoDB, Redis, Kafka, CSV, an HTTP API), scaffolding an okf-* skill, or extending the project to a new source. Instructions-only; no binary required.

Yurii Serhiichuk · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add xSAVIKx/okf-skills --skill okf-producer-generator

技能说明


name: okf-producer-generator description: Guidance and the bundled OKF specification for building a new Open Knowledge Format (OKF) producer/connector skill in this project — the architectural principles, the okf-go library contract, the produce/ingest/schema command surface, the secret-handling and sync conventions, and the exact registration steps. Use when creating a new OKF connector or producer for a data source the project does not yet cover (e.g. MongoDB, Redis, Kafka, CSV, an HTTP API), scaffolding an okf-* skill, or extending the project to a new source. Instructions-only; no binary required. license: Apache-2.0 metadata: version: "0.4.0" author: Yurii Serhiichuk tags: "okf, producer, connector, skill-authoring, scaffolding, schema, agent-guidance, documentation, code-generation"

OKF Producer Skill Generator

This skill teaches a coding agent (Claude Code, Cursor, Gemini CLI, Copilot, …) how to author a new producer for this project: a standalone CLI skill that extracts metadata from a data source into an Open Knowledge Format (OKF) bundle, and ingests/syncs descriptions back. It ships the OKF spec it must conform to, the conventions every existing connector follows, and the exact wiring steps so the new skill builds, tests, and is auto-discovered over MCP.

Google introduced OKF and invited the community to "write a producer, write a consumer." This skill is how you write a producer here — one that matches the six that already exist (okf-sqlite, okf-mysql, okf-postgresql, okf-bigquery, okf-fs, okf-git) instead of reverse-engineering them.

When to Use

Load this skill when asked to:

  • Add a new data source — "make an OKF connector for MongoDB / Redis / Kafka / CSV / an API".
  • Scaffold an okf-* producer skill, or extend the project to a source it doesn't cover.

Do not use it for: reading a bundle (use okf-reader), enriching descriptions (use okf-enrich), or building a consumer that only reads OKF (the spec in okf-SPEC.md is enough for that).

Read the spec first

The format your producer must emit is defined in okf-SPEC.md (bundled here; canonical source is okf-go/okf-SPEC.md). The library API you build against is in okf-go-api.md. Skim both before designing concept types. The rules you will lean on most:

  • A bundle is a directory tree of markdown files with YAML frontmatter.
  • The only required frontmatter field is type; everything else is optional.
  • index.md files carry no frontmatter, except the bundle-root index.md, which may declare only okf_version: "0.2".
  • Consumers are permissive: unknown type values, extra keys, and broken links are all tolerated. Conformance is just "every concept has parseable frontmatter with a non-empty type."

The five principles that define a producer

These are not obvious from reading one connector. Internalize them before writing code.

  1. Deterministic extraction — no embedded LLM. produce and ingest are mechanical: read the source, emit/compare markdown. Never call an LLM inside produce to write descriptions. Emit a deterministic placeholder (e.g. fmt.Sprintf("MongoDB collection %s", name)); the meaning is added later by okf-enrich, which uses the agent's own LLM. (This project deliberately deleted an embedded second model — a model calling a tool that calls another model is redundant cost and usually worse output.)

  2. okf-go is the single source of OKF types. Import it; never redefine Frontmatter or ConceptDoc. Its WriteConceptDoc/ReadConceptDoc and section helpers are what keep your output spec-conformant and round-trippable.

  3. schema is the contract. Implement the schema subcommand and okf-mcp auto-discovers your binary and exposes produce/ingest as MCP tools — no okf-mcp changes ever needed. Secret-bearing flags declare an Env binding so okf-mcp passes them via the environment, never argv.

  4. Always three subcommands: produce, ingest, schema. Register flags on a per-subcommand flag.NewFlagSet(...) — never global flag.Bool(...).

  5. Portable, pure Go. Zero CGO — verify any source driver you add is pure Go (e.g. modernc.org/sqlite not mattn/go-sqlite3; MongoDB's go.mongodb.org/mongo-driver is cgo-free). One binary named okf-<name>. Give the module its full publishable path and require okf-go at its published version — no replace; go.work maps it locally (see below).

Anatomy of a producer skill

skills/okf-<name>/
├── SKILL.md        # frontmatter (spec-compliant) + When to Use / Setup / produce / ingest / schema
├── go.mod          # module github.com/xSAVIKx/okf-skills/skills/okf-<name>; go 1.24.0; require okf-go v0.1.0 (no replace; go.work maps it locally)
├── main.go         # main() router + runProduce + runIngest + source-specific helpers
├── schema.go       # buildSchema() okf.SkillSchema
└── *_test.go       # schema_test.go (asserts name + commands) + a pure-function test

The cleanest starting point is to copy skills/okf-sqlite/ (the minimal, dependency-light reference producer) and adapt it. For a live-server source that needs credentials, also look at skills/okf-mysql/ for the env-secret pattern; for a non-tabular / file-like source, look at skills/okf-fs/ and skills/okf-git/.

Build sequence

1. Map the source to OKF concepts

Decide: the concept type string (e.g. "MongoDB Collection"); the bundle layout (a subdirectory like tables/ for SQL or collections/ for Mongo); and the Resource URI scheme that uniquely identifies each asset (sqlite:///…/orders, bigquery://proj/ds/tbl). Strip any credentials from the URI before putting it in Resource — it is written to disk.

2. Scaffold the module

Copy okf-sqlite to skills/okf-<name>/, then set the module path to `github.com/

阅读完整来源 ↗