skills.rest
thedutchvisiongroup
thedutchvisiongroupOFFICIAL
Explore all skills by this author →
WebsiteGitHub

writing-okf

Creates and validates Open Knowledge Format markdown documents with YAML frontmatter.

Updated Mar 28, 2026
Search Tags:#documentation#markdown#knowledge management#validation#yaml frontmatter#knowledge bundle#okf
One-click install
npx skills add https://github.com/thedutchvisiongroup/agent-skills --skill writing-okf-thedutchvisiongroup
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-okf
Source: https://github.com/thedutchvisiongroup/agent-skills/tree/main/skills/writing-okf
Command: npx skills add https://github.com/thedutchvisiongroup/agent-skills --skill writing-okf-thedutchvisiongroup

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) components.

What problem does it solve? Teams need machine-readable, agent-friendly knowledge documentation about data assets, services, APIs, and processes, but ad-hoc markdown notes lack consistent structure, provenance, and validation. This Skill standardizes how OKF (Open Knowledge Format) documents are written, organized, and checked. ## Core Features & Use Cases - Structured OKF authoring: Writes markdown concept documents with YAML frontmatter following the OKF v0.2 spec, including type, provenance (generated/sources), lifecycle status, and cross-linking conventions. - Bundle scaffolding management: Maintains same-level index.md and log.md files in every directory of a knowledge bundle for progressive disclosure and change history. - Automated validation: Runs validate_okf.py to check spec conformance ([SPEC] findings) and house conventions ([HOUSE] findings) across an entire bundle recursively, with JSON output for agents. - Use Case: After building a new data pipeline, ask the agent to document the tables and endpoints as OKF concepts — it locates the bundle, drafts documents from ready-made templates, updates the directory index and log, and validates everything. ## Quick Start Document the customers table as an OKF concept in our knowledge bundle and validate the whole bundle afterwards.

Frequently Asked Questions about writing-okf

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an OKF document for a data table or API?▼

Create a lowercase-kebab-case markdown file with YAML frontmatter containing a type field plus title, description, tags, generated, and status. Use the per-type templates in references/concept-templates.md for tables, API endpoints, services, and playbooks, then update the directory's index.md and log.md.

How do I validate an OKF knowledge bundle?▼

Run python3 scripts/validate_okf.py on the bundle root; it recursively validates every markdown file and checks directory scaffolding in one pass. Add --json for machine-readable output. [SPEC] findings must always be fixed; [HOUSE] findings are conventions fixable unless waived.

What is the difference between OKF spec rules and house rules?▼

The OKF v0.2 spec only requires valid UTF-8 markdown with parseable frontmatter containing a non-empty type field. House rules are stricter: kebab-case filenames, non-empty bodies, mandatory index.md/log.md scaffolding, same-level index links, and required generated/status provenance fields.

Can index.md link to files in subdirectories?▼

No. Index and log files may only reference same-level concept files and direct subdirectories (as subdir/). Nested paths, parent-directory escapes, and bundle-absolute links are forbidden in index.md and log.md; each subdirectory maintains its own scaffolding.

When should I not use OKF documents?▼

Avoid OKF for trivial notes better suited to code comments, documentation that belongs in another format such as OpenAPI specs, and temporary throwaway content. OKF targets durable, machine-readable knowledge about systems, data, and processes.

Related Skills

Explore More Software Engineering Skills→
onelee85onelee85

gsd-forensics

Analyze git history and artifacts to document failed GSD workflow root causes.

Community
Advanced
yzflyyzfly
46

okf-creator

Convert code repositories, documents, schemas, and notes into OKF v0.1 knowledge bundles.

Community
Advanced
amak07amak07

create-adr

Generate MADR-format Architecture Decision Records with sequential numbering and YAML frontmatter.

Community
Intermediate
mardenneubertmardenneubert
12

api-designer

Convert DMML domain models into OpenAPI 3.1 specifications with REST endpoints.

Community
Advanced