Skip to content

jkroepke/okf-crossplane-v2 / .agents/skills/okf-open-knowledge-format

okf-open-knowledge-format

Verified

Create, validate, and enrich Open Knowledge Format (OKF) bundles — the open spec for representing organizational knowledge as markdown files with YAML frontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format', 'knowledge bundle', 'OKF bundle', 'create a knowledge base for agents', 'validate OKF', 'convert to OKF', 'enrich knowledge docs', 'agent-readable knowledge', 'LLM wiki', 'knowledge catalog', 'kcmd', or wants to structure knowledge as markdown files for AI agent consumption. Also use when the user has a directory of markdown files and wants to make them interoperable or conformant with the OKF standard. Even for simple requests like 'make this folder OKF conformant' — the skill has critical structural rules the agent needs.

FileKindSize
SKILL.mdskill md15.2 KB
references/conversion.mdmarkdown4.3 KB
references/examples.mdmarkdown6.9 KB
references/spec-v02.mdmarkdown36.7 KB
scripts/validate.shexecutablescript3.0 KB

references/conversion.md

View on GitHub
# Converting Sources to OKF

Guides for transforming existing knowledge into conformant OKF bundles.

---

## From Notion Export

Notion exports as markdown with properties in YAML-like format.

### Steps

1. **Export** from Notion as Markdown & CSV
2. **Clean filenames** — remove UUID suffixes (`Page Name abc123def.md` → `page-name.md`)
3. **Map properties to frontmatter:**

| Notion Property | OKF Field |
|-----------------|-----------|
| Type (select) | `type` (required) |
| Name | `title` |
| Tags (multi-select) | `tags` |
| Last Edited | `generated.at` (with an identified importer in `generated.by`) |
| URL | `resource` |

4. **Convert links** — Notion uses `[Page Name](Page%20Name%20abc123def.md)`. Convert to clean relative paths: `[Page Name](./page-name.md)`
5. **Remove Notion artifacts** — empty toggle blocks, breadcrumb headers, cover image references
6. **Add missing `type` field** — if Notion had no "Type" property, ask the user what type to assign

### Edge cases

- Notion databases: each row becomes a concept. Database title becomes the directory name.
- Nested pages: respect the hierarchy. Child pages go in subdirectories.
- Inline databases: flatten into a list in the parent concept's body.
- Notion formulas/rollups: drop them — they don't translate to static markdown.

---

## From Obsidian Vault

Obsidian vaults are already close to OKF. Main differences: wikilinks and potentially missing `type` field.

### Steps

1. **Convert wikilinks to standard links:**
   - `[[Note Name]]` → `[Note Name](./note-name.md)`
   - `[[Note Name|Display Text]]` → `[Display Text](./note-name.md)`
   - `[[Note Name#Heading]]` → `[Note Name](./note-name.md#heading)`

2. **Ensure `type` field exists** in every frontmatter block. Common mappings:

| Obsidian pattern | Suggested OKF type |
|------------------|--------------------|
| Daily notes | `Log` |
| MOC / index note | Convert to `index.md` (reserved file) |
| Permanent notes | `Reference` |
| Literature notes | `Reference` |
| Project notes | `Playbook` or domain-specific |

3. **Convert tags:**
   - Inline `#tag` → move to frontmatter `tags: [tag]`
   - Nested `#parent/child` → flatten to `tags: [parent, child]` or keep as `parent/child`

4. **Handle embeds:**
   - `![[Note]]` — convert to a regular link or inline the content
   - `![[image.png]]` — keep as standard markdown image `![](./image.png)`

5. **Remove Obsidian-specific syntax:**
   - `%%comments%%` → remove
   - `> [!callout]` → convert to blockquote or heading
   - Dataview queries → remove (dynamic, not portable)

### What to keep as-is

- Standard markdown formatting (headings, lists, tables, code blocks)
- Existing YAML frontmatter (just add `type` if missing)
- Standard markdown links (already OKF-compatible)
- Mermaid diagrams (standard markdown fenced blocks)

---

## From CSV / Spreadsheet

Each row becomes one concept document.

### Steps

1. **Identify column mapping:**

| Column role | Maps to |
|-------------|---------|
| Primary identifier / name | Filename (slugified) |
| Category / kind | `type` field |
| Short description | `description` field |
| Tags / labels | `tags` field |
| URL / link | `resource` field |
| Last modified date | `generated.at` (with the import process in `generated.by`) |
| All other columns | Body content (as table or sections) |

2. **Generate one `.md` per row:**

```markdown
---
type: {category_column}
title: {name_column}
description: {description_column}
tags: [{tag1}, {tag2}]
generated: { by: "process:spreadsheet-import", at: "{date_column}T00:00:00Z" }
---

# {name_column}

| Field | Value |
|-------|-------|
| Column3 | {value} |
| Column4 | {value} |
```

3. **Generate index.md** from the full list:

```markdown
# {Sheet Name}

- [{row1_name}](./{row1_slug}.md) - {row1_description}
- [{row2_name}](./{row2_slug}.md) - {row2_description}
```

4. **Generate log.md** with creation entry:

```markdown
# Update Log

## {today_iso8601}
- **Creation**: Generated {N} concepts from spreadsheet import.
```

### Edge cases

- Empty cells: omit the field entirely (don't write empty strings)
- Multi-value cells (comma-separated): parse into YAML list for `tags`
- Very long text cells: put in body as a section, not in frontmatter
- Duplicate names: append a disambiguator (e.g., `widget-v1.md`, `widget-v2.md`)
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall