| name | okf-knowledge-authoring |
| description | An OKF knowledge bundle (`docs/knowledge/`) is only useful if agents can trust it. Three failure modes rot it: (1) a concept **restates a decision or schema** and then drifts from the real source, becoming a second, wron |
| source_type | skill |
| source_file | skills/okf-knowledge-authoring.md |
okf-knowledge-authoring
Migrated from skills/okf-knowledge-authoring.md.
Codex packaging notes
- Claude/Telar source files remain the source of truth; this file is the generated Codex adapter.
- Skill-local support files from the original Telar skill, such as
references/... or workflow/..., are packaged beside this SKILL.md.
- Repo-root references from the original Telar file, such as
agents/..., commands/..., scripts/..., resources/..., rules/..., hooks/..., or templates/..., are packaged at this plugin root.
- The original Telar orchestration source (
skills/orchestration/...) is packaged under source/skills/orchestration/... for exact-reference lookups; all other Telar skills exist here only as the generated adapters under the plugin-root skills/ directory.
- Resolve plugin-root paths from this generated skill directory via
../.. when reading support files or running packaged scripts.
okf-knowledge-authoring
Problem
An OKF knowledge bundle (docs/knowledge/) is only useful if agents can trust it. Three failure modes rot it: (1) a concept restates a decision or schema and then drifts from the real source, becoming a second, wrong source of truth; (2) a concept has no citation, so no reader can verify it; (3) a concept leaks data rows, PII, or secrets into a file that is world-readable within the repo. Authoring without a contract produces exactly these.
Solution
Author every concept against one contract. The bundle is a derived, machine-facing view of docs/adr/ (decisions) and docs/data_model/ (schema) — never a second source.
1. Format (OKF v0.1)
- One
.md file = one concept (a table, term, metric, playbook…). Reserved filenames: index.md (navigation / progressive disclosure, no required frontmatter) and log.md (change history, ## YYYY-MM-DD headings, newest first).
- YAML frontmatter's only required key is
type (non-empty). Recommended: title, description, resource (canonical URI), tags, timestamp (ISO 8601). Extra keys are fine — consumers must tolerate unknown keys.
- Relationships are ordinary markdown links between concepts (
[x](/core/tables/x.md) or [x](./x.md)); the link graph is richer than the directory tree. Consumers must tolerate broken links.
A minimal table concept (docs/knowledge/core/tables/candidates.md):
---
type: Postgres Table
title: candidates
description: One row per candidate profile.
resource: https://console.example/db/candidates
tags: [core, identity]
timestamp: 2026-07-08T00:00:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `id` | uuid | Primary key. |
| `employer_id` | uuid | FK to [employers](/core/tables/employers.md). |
# Joins
Joined with [employers](/core/tables/employers.md) on `employer_id`.
# Citations
- Schema: [data_model/core/04](/docs/data_model/core/04-schema.md)
- Decision: ADR-0043 (documentation IA)
2. Authority & citations (one-way)
- On any conflict, the ADR / schema wins and you correct the concept — never the reverse.
- Never originate a decision in a concept. New rules land in an ADR or the schema spec first; the concept encodes an already-ratified fact.
- Every concept links its origin under a
# Citations heading (ADR / EDR / spec path). A concept without a citation is incomplete.
- Bias content toward the non-derivable: relationships, business meaning, cross-cutting rules — not schema an agent can already read from the DDL.
3. PII & security boundary (binding)
- Schema, semantics, and metadata only — never data rows, never personal data.
- No secrets, tokens, connection strings, or
service_role material. resource URIs point at consoles/paths, not credentials.
- Rule of thumb: nothing may appear here that could not sit in a code comment.
4. Naming & scope
core concepts use neutral names (e.g. Candidate, Employer); vertical scopes may use concrete names. A core change that a vertical overrides gets a concept in that vertical scope — do not branch inside a core concept.
5. Maintenance (source-first, same change)
- Source first — land the change in the migration /
data_model / ADR (its authoritative home).
- Then derive — update the matching
docs/knowledge/<scope>/… concept and append a log.md entry.
- Removal — when a concept's source is deleted upstream, delete the concept (and any links to it) and log the removal.
- PII gate — re-confirm §3 on every edit.
Source and bundle move together within one change, not in a separate later pass (analogous to the schema expand → migrate → contract gate).
6. Cross-linking (the value multiplier)
Wire concepts so an agent starting anywhere reaches what it needs: RPC → table, Access Policy → table, Invariant → RPC/table, Scenario → Screen → RPC → table, Decision → concept. Use ordinary markdown links; path = entry name.
7. Validation checklist (before merge)
