okf-enrich
Guidance for an AI agent to enrich an Open Knowledge Format (OKF) bundle with high-quality concept descriptions using its own LLM — grounded in the bundle's schema, data profile, and samples — then optionally sync them back to the source. Use when an OKF bundle has missing, weak, or low-quality descriptions that should be improved before publishing or ingestion. Instructions-only; no binary required.
Yurii Serhiichuk · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add xSAVIKx/okf-skills --skill okf-enrich技能说明
name: okf-enrich description: Guidance for an AI agent to enrich an Open Knowledge Format (OKF) bundle with high-quality concept descriptions using its own LLM — grounded in the bundle's schema, data profile, and samples — then optionally sync them back to the source. Use when an OKF bundle has missing, weak, or low-quality descriptions that should be improved before publishing or ingestion. Instructions-only; no binary required. license: Apache-2.0 metadata: version: "0.4.0" author: Yurii Serhiichuk tags: "okf, enrichment, documentation, agent-guidance, prompt-engineering"
OKF Bundle Enrichment Guidance Skill
This skill teaches an AI agent (Claude Code, Cursor, Gemini CLI, Copilot, …) how to enrich an Open Knowledge Format (OKF) bundle — adding or improving the human-readable description of each concept (table, dataset, file, directory) — using the agent's own LLM.
There is deliberately no binary and no embedded model here. Generating a good description is a judgment task, and the harness driving the project already has a capable LLM in the loop. Embedding a second one would mean a model calling a tool that calls another model: redundant cost, an extra API key to manage, and usually a worse result than the model already doing the work. So enrichment is delivered as guidance — the procedure and the quality bar — for whatever LLM is present, exactly as okf-reader is guidance for reading a bundle.
When to Use
Load this skill when asked to enrich, document, describe, annotate, or "improve the descriptions in" an OKF bundle — typically after a connector has produced the bundle and before syncing descriptions back to the source.
Pairs with:
okf-reader— follow its rules to read and navigate the bundle efficiently (index-first, frontmatter-only when possible, grep for targeted lookups).- the connectors (
okf-sqlite,okf-mysql,okf-postgresql,okf-bigquery,okf-fs,okf-git) — the producers and the sync target. Enrichment is far better when the bundle was produced with--profileand--sample(the four SQL connectors), and the descriptions you write can be pushed back to the origin with the connector'singest --sync.
The OKF concept document
Each concept is a markdown file with YAML frontmatter:
---
type: SQLite Table
title: orders
description: # <- the field you write
resource: sqlite:///.../orders
tags: [sqlite, table]
timestamp: 2026-06-13T12:00:00Z
---
# Columns
| Name | Type | Primary Key | Nullable | Default |
| --- | --- | --- | --- | --- |
## Data Profile # present only when produced with --profile
| Column | Non-Null | Null | Distinct | Min | Max |
| --- | --- | --- | --- | --- | --- |
## Sample # present only when produced with --sample
| id | customer_id | total | status |
| ...
Your enrichment target is the frontmatter description field. For sources that carry per-column comments (MySQL, PostgreSQL, BigQuery — their # Columns table includes a Comment/Description column), you may also fill the empty cells in that column.
Procedure
1. Discover concepts (index-first)
Follow the okf-reader rules: read index.md first and use it to locate concept files; route directly to the files you need. Do not recursively read the whole bundle.
To see exactly what still needs work — and to re-measure after enriching — run the deterministic, no-LLM coverage report: okf-viz coverage --bundle <dir> (add --json for machine output, --min <pct> to gate in CI). It reports the percentage of non-placeholder descriptions, columns commented, broken cross-links, concepts missing a type, and orphan nodes.
2. Decide what to enrich
Enrich a concept when its description is empty or a generic placeholder the connector inserted (e.g. "SQLite table orders", "File config.yaml", "No description available", "Git file main.go"). Do not overwrite a substantive, human- or source-authored description unless the user explicitly asks you to regenerate. This keeps the operation idempotent and safe to re-run.
3. Gather grounding (never guess)
Base every claim on evidence in the document. Read only what you need:
- Schema (
# Columns): names, types, keys, nullability → the shape of the concept. ## Data Profile(if present): per-column non-null / null / distinct / min / max. Signals: a 2–3-distinct column is likely a flag, enum, or status; min/max timestamps reveal the time span the data covers; a high null ratio flags optional fields.Semanticcolumn andValues:set (when present): the connector now detects a column's semantic type deterministically (email,uuid,iso-timestamp,monetary,boolean,enum,fk-ish) and, for low-cardinality columns, lists the literal distinct values ascol ∈ {…}. Treat these as primary, near-mechanical grounding — anenumcolumn with itsValuesset is almost a description on its own; restate it rather than re-deriving it from samples.
## Sample(if present): real example rows — the strongest signal for what the data actually means.- Relationships: links in the body to other concept files → how this concept connects to others.
If the profile/sample sections are absent, enrich from the schema alone — but prefer to (re)produce the bundle with --profile --sample first when you can; it yields markedly better descriptions.
4. Write the description
- Grain first: state what one row / record / file represents, then its purpose — e.g. "One row per customer order, capturing line-item totals, payment status, and the placing customer."
- Length: one sentence for a table / dataset / file; a short noun phrase for a column.
- Ground every claim in the schema/profile/sample. Do not invent business meaning the evidence doesn't support. If the purpose is genuinely ambiguous, des