Skills — markdown that teaches the agent

OpenKnowledge ships skills as SKILL.md files — YAML frontmatter plus a markdown body — and installs them into each harness's own skill directory during ok init. This is the same family as Claude Code's skills-as-md: agent expertise lives in markdown, not code.

1. Anatomy of a skill

# packages/server/assets/skills/discovery/SKILL.md:1-9
---
name: open-knowledge-discovery
description: "Read when the user asks what OpenKnowledge is..."
compatibility: "Any agent host — no MCP server required..."
metadata:
  version: "0.19.1"
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge"
---

The body is a narrative contract: when to read this skill, what commands are available, the read/write conventions. Crucially, the compatibility line says "Any agent host — no MCP server required." The skill is written so an agent can use OpenKnowledge with nothing but ls/cat/grep over the files. MCP is an upgrade, not a requirement — the skill is the floor, MCP is the ceiling.

2. Cross-harness install

The skill lands wherever each harness looks for skills, driven by the same EditorMcpTarget.projectSkillPath adapter as the MCP config (02_harness_integration.md):

write-project-skill.ts:57-91 copies the bundled packages/server/assets/skills/project/SKILL.md into each location, and ok init --upgrade re-syncs them. So one source skill fans out to every connected agent — the agent doesn't need to know it's talking to OpenKnowledge; the skill teaches it in the agent's native skill mechanism.

3. The skill library

The repo ships roughly 11 skills under packages/server/assets/skills/. Two kinds:

• Operational skills that pair with the MCP workflows: discovery (what OK is, how to reach it), project (the per-project read/write contract installed by ok init), bug-report.
• Domain "packs" that shape what kind of wiki the agent builds: worldbuilding, writing-pipeline, plain-notes, codebase-wiki, okf, entity-vault, knowledge-base, software-lifecycle.

The packs are the surprising bit: the same 17 MCP tools become a worldbuilding bible, an engineering wiki, or a personal notes vault depending on which skill markdown is loaded. The tools are fixed; the skill is the personality. That is a strong reuse story — you ship one tool surface and specialize behavior entirely in markdown.

4. Two distribution channels

• Project-local (ok init) — skill files committed (or git-excluded) into the repo, tied to that project's init state.
• Claude Desktop bundle — ok install-skill (and the desktop bridge.skill.buildAndOpen, packages/desktop/src/main/ipc/install-skill.ts:32,68,105) builds a claude-cowork skill ZIP saved to Downloads as openknowledge.skill, for upload into Claude Desktop where there's no project directory to scaffold.

What's worth stealing

1. Skill as the floor, MCP as the ceiling. Writing the skill to work with bare shell means your integration never hard-fails when MCP is unavailable. Design the markdown contract so the agent can limp along without your server.
2. One tool surface, many personalities. Specialize behavior in markdown packs, not in code branches. For a review meta-harness: one tool surface, swappable "review style" skills (security review, perf review, style review).
3. Install into the agent's native skill dir. Don't invent a skill format — drop SKILL.md where Claude/Cursor/Codex already look. The adapter that knows the MCP config path also knows the skill path.
4. A separate bundle channel for app-only hosts (Claude Desktop) where there's no repo to scaffold.