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.mdfiles carry no frontmatter, except the bundle-rootindex.md, which may declare onlyokf_version: "0.2".- Consumers are permissive: unknown
typevalues, extra keys, and broken links are all tolerated. Conformance is just "every concept has parseable frontmatter with a non-emptytype."
The five principles that define a producer
These are not obvious from reading one connector. Internalize them before writing code.
-
Deterministic extraction — no embedded LLM.
produceandingestare mechanical: read the source, emit/compare markdown. Never call an LLM insideproduceto write descriptions. Emit a deterministic placeholder (e.g.fmt.Sprintf("MongoDB collection %s", name)); the meaning is added later byokf-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.) -
okf-gois the single source of OKF types. Import it; never redefineFrontmatterorConceptDoc. ItsWriteConceptDoc/ReadConceptDocand section helpers are what keep your output spec-conformant and round-trippable. -
schemais the contract. Implement theschemasubcommand andokf-mcpauto-discovers your binary and exposesproduce/ingestas MCP tools — nookf-mcpchanges ever needed. Secret-bearing flags declare anEnvbinding sookf-mcppasses them via the environment, never argv. -
Always three subcommands:
produce,ingest,schema. Register flags on a per-subcommandflag.NewFlagSet(...)— never globalflag.Bool(...). -
Portable, pure Go. Zero CGO — verify any source driver you add is pure Go (e.g.
modernc.org/sqlitenotmattn/go-sqlite3; MongoDB'sgo.mongodb.org/mongo-driveris cgo-free). One binary namedokf-<name>. Give the module its full publishable path and requireokf-goat its published version — noreplace;go.workmaps 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/