What Is an OKF Skill? — A Guide to AI Agent Skills in Open Knowledge Format

What Makes an OKF Skill Different

OKF skills are a specialized subset of OKF bundles. While a general OKF bundle informs — providing reference documentation, API specs, or conceptual knowledge — an OKF skill instructs. A skill tells an AI agent how to do something, step by step, with executable patterns.

Skills Teach Capabilities, Not Just Inform

A knowledge bundle about Python would describe the language's syntax, standard library, and ecosystem. A Python OKF skill, by contrast, would contain instructions for how an agent should write, review, or debug Python code — including code style rules, error-handling patterns, testing requirements, and file organization conventions. The skill teaches the agent a capability, not a subject.

Skills Are Structured for Agent Execution

OKF skills use a consistent structure that AI agents recognize as executable instructions:

• Calling conventions — how an agent should invoke the skill (e.g., "When the user asks to distill a video, load the Lineage Skill")
• Step-by-step procedures — numbered actions the agent follows
• Behavioral rules — constraints and preferences (e.g., "Always validate frontmatter before writing")
• Output templates — the exact format the agent should produce
• Examples — worked-through demonstrations of the skill in action

Skills Can Be Combined and Composed

OKF skills are composable. An agent can load multiple skills simultaneously, each contributing a different capability. For example, an agent might load a documentation skill (how to write docs), a frontmatter validation skill (how to check YAML), and a knowledge-distillation skill (how to extract key points from source material) — all working together in one session.

How OKF Skills Work

Structure: Markdown + YAML Frontmatter

Like all OKF bundles, skills are directories of markdown files with YAML frontmatter. The key difference is that a skill's index.md acts as a manifest describing the skill's purpose, invocation, and behavioral expectations:

---
title: My Agent Skill
description: Teaches an agent to perform domain-specific tasks
tags: [skills, okf, agent-capability]
version: "1.0.0"
author: Your Name
okf_version: "0.1"
type: skill
---

# My Agent Skill

## Purpose
This skill teaches the agent how to [perform a specific task].

## When to Use
Load this skill when the user asks about [topic] or requests [action].

## Instructions

1. First, [step one with details]
2. Then, [step two]
3. Finally, [step three]

## Rules

- Always [constraint one]
- Never [constraint two]
- Use [format/pattern] for output

## Examples

### Example 1: [Scenario]
[Walk through the skill in action]

How Agents Load and Use Skills

Different AI agents load OKF skills in different ways:

Claude Code

Claude Code discovers skills from the ~/.claude/skills/ directory. Any OKF bundle placed in this directory is auto-loaded into Claude's context. Agents reference skills by their name or description in prompts:

# Install a skill
git clone https://github.com/JuneYaooo/lineage-skill.git ~/.claude/skills/lineage-skill

# Use it — Claude automatically detects available skills
claude "Distill this course transcript using the Lineage Skill"

OpenCode / Codex

OpenCode and Codex (by Nous Research) support OKF skills through the .opencode/ directory. Skills can be symlinked or copied into the agent's knowledge directory and are discovered at session start.

Generic Agent Integration

Any LLM-based agent can consume an OKF skill by reading its index.md and following its instructions:

# Load skill instructions into agent context
cat ~/skills/my-skill/index.md
cat ~/skills/my-skill/instructions/*.md

Skills vs. General Knowledge Bundles

Some bundles blur the line — they contain both reference knowledge and procedural instructions. These hybrid bundles are tagged with both domain tags and skill tags.

How AI Agents Load and Use Skills

The most popular agent platforms use different mechanisms to discover and load OKF skills:

Claude Code Skill System

Claude Code has a first-class skill system. Skills are OKF bundles placed in ~/.claude/skills/. Claude discovers them automatically and users invoke them conversationally:

# ~/.claude/skills/ directory structure
~/.claude/skills/
├── lineage-skill/
│   ├── index.md
│   ├── instructions/
│   └── templates/
├── okf-knowledge-skill/
│   ├── index.md
│   └── concepts/
└── okf-frontmatter/
    ├── index.md
    └── scripts/

Manual Loading

For agents without a native skill system, you can load skills by including their content in the system prompt or context window:

# Load a skill into any agent's context
SKILL_DIR="$HOME/skills/my-skill"
echo "=== Loading Skill: $(head -1 $SKILL_DIR/index.md) ==="
cat $SKILL_DIR/**/*.md

How to Create Your Own OKF Skill

Creating an OKF skill follows the same process as creating a knowledge bundle, with a few skill-specific additions:

Step 1: Define the Capability

Clearly define what you want the skill to teach. What task should the agent be able to perform after loading the skill? Write this as a one-sentence purpose statement.

Step 2: Create the Skill Directory

mkdir my-agent-skill
cd my-agent-skill

Step 3: Write index.md with Skill Metadata

Include type: skill in your frontmatter and tag it with skills:

---
title: My Agent Skill
description: Teaches agents to perform [specific capability]
tags: [skills, okf, your-domain]
type: skill
version: "0.1.0"
author: Your Name
okf_version: "0.1"
---

# My Agent Skill

## Purpose
[One sentence describing the capability]

## When to Use
[When should the agent activate this skill?]

## Instructions
[Step-by-step process]

## Rules
[Behavioral constraints]

## Examples
[Worked-through demonstrations]

Step 4: Add Supporting Concepts

Create subdirectories for templates, examples, and reference materials that the skill needs:

my-agent-skill/
├── index.md
├── instructions/
│   ├── setup.md
│   └── execution.md
├── templates/
│   └── output-template.md
└── examples/
    └── basic-usage.md

Step 5: Publish and Submit

Push to GitHub and submit to BundleDex with the skills tag so other users can discover your skill.

Best OKF Skills in the BundleDex Index

These are the top OKF skills currently indexed on BundleDex, ranked by GitHub stars:

Browse all 583 bundles on BundleDex, or filter by the skills tag to discover more.

FAQ