Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Point the shipped skills at the docs and source (PRD-8110) (#3714)

serafin-garciaf1f3239a4e24
diff --git a/.changeset/agent-capability-lookup.md b/.changeset/agent-capability-lookup.md
new file mode 100644
index 000000000..2b666b83d
--- /dev/null
+++ b/.changeset/agent-capability-lookup.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Agents now know to look things up rather than guess at what OpenKnowledge can do. The shipped skills describe the core editing flow, so a request touching anything outside it depended on the agent already happening to know the feature existed. Both skills now point at the documentation site and the source repository.
+
+**Re-run `ok init` in an existing project to pick this up.** The project-local skill is seeded only when absent, so opening an already-initialized project does not refresh it. The user-global discovery skill does refresh on upgrade.
diff --git a/packages/server/assets/skills/discovery/SKILL.md b/packages/server/assets/skills/discovery/SKILL.md
index ab879a1c3..e38e9397d 100644
--- a/packages/server/assets/skills/discovery/SKILL.md
+++ b/packages/server/assets/skills/discovery/SKILL.md
@@ -1,6 +1,6 @@
---
name: open-knowledge-discovery
-description: "Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to open or preview a single markdown file that is not part of an OpenKnowledge project, wants to share an OpenKnowledge project with collaborators, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill installed into each detected agent's skills dir (for example `.claude/skills/open-knowledge/`) whenever `ok init` runs."
+description: "Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to open or preview a single markdown file that is not part of an OpenKnowledge project, wants to share an OpenKnowledge project with collaborators, asks whether OpenKnowledge supports a particular capability, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill installed into each detected agent's skills dir (for example `.claude/skills/open-knowledge/`) whenever `ok init` runs."
compatibility: "Any agent host — no MCP server required. Pure discovery + install guidance."
metadata:
author: "Inkeep"
@@ -116,6 +116,13 @@ The path must be absolute (a file outside a project has no cwd to anchor a
relative path). Re-opening the same file lands on the same session. Never
construct or guess the URL — use the one `preview_url` returns.
+## What else OK does
+
+This skill does not enumerate OK's capabilities, and they change between releases. When asked whether OK supports something, read rather than guess:
+
+- **Docs** — <https://openknowledge.ai/docs>
+- **Source** — <https://github.com/inkeep/open-knowledge>
+
## Working inside a project — use the project-local skill, not this one
Do **not** use this skill to perform OpenKnowledge reads or writes. The
@@ -132,5 +139,4 @@ directory was not committed). Advise the user to run `ok init` to install it.
## Learn more
-- Repository: <https://github.com/inkeep/open-knowledge>
- Run `ok --help` for the full command list.
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index e84693143..e1a2e5bd4 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -123,6 +123,14 @@ Research and consolidate arrive with `ok seed --pack knowledge-base`. **Without
Don't chain silently: let the user drive ingest → research → consolidate, and a procedure's STOP gates override session-level "don't stop to ask" hints. After any turn that changes KB content, check for a `log.md` and follow its contract (`references/cadence-and-logs.md`). Interleave a multi-doc batch so the preview shows narrative progress.
Onboarding a repo that already has content: `references/onboard-existing-repo.md`. Layer model + packs: `references/starter-packs.md`.
+
+## Capabilities beyond this skill
+
+OK does more than this skill describes, and what it does changes between releases. When a request implies something not covered here, read rather than guess:
+
+- **Docs** — <https://openknowledge.ai/docs>
+- **Source** — <https://github.com/inkeep/open-knowledge>
+
## Server lifecycle
If `write` / `edit` returns `"Hocuspocus server is not running"`, run `ok start` (via Bash) and retry. Never fall back to native `Edit` / `Write` for in-scope markdown.
diff --git a/packages/server/src/skill-capability-lookup-contract.test.ts b/packages/server/src/skill-capability-lookup-contract.test.ts
new file mode 100644
index 000000000..d3b9f9c29
--- /dev/null
+++ b/packages/server/src/skill-capability-lookup-contract.test.ts
@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+
+/**
+ * Guards the capability-lookup pointers in both bundled skills.
+ *
+ * The skills describe the core editing flow, so anything outside it is only
+ * reachable if the agent knows to look it up. Two properties are load-bearing
+ * and neither is enforced by anything else:
+ *
+ * - The discovery skill's `description` names capability questions. That field
+ * is the skill's activation contract — the section below it never loads on a
+ * capability ask without the clause, so dropping it silently disables the
+ * pointer while leaving the prose in place.
+ * - Both skills carry the docs and source URLs. These are the whole mechanism;
+ * losing one leaves the framing sentence pointing nowhere.
+ *
+ * The sections deliberately name no individual capability: an enumerated list
+ * drifts as features ship, which is the failure this guidance exists to avoid.
+ */
+
+const PROJECT_SKILL_PATH = join(import.meta.dir, '../assets/skills/project/SKILL.md');
+const DISCOVERY_SKILL_PATH = join(import.meta.dir, '../assets/skills/discovery/SKILL.md');
+
+const DOCS_URL = 'https://openknowledge.ai/docs';
+const SOURCE_URL = 'https://github.com/inkeep/open-knowledge';
+
+describe('bundled skills — capability lookup contract', () => {
+ const project = readFileSync(PROJECT_SKILL_PATH, 'utf-8');
+ const discovery = readFileSync(DISCOVERY_SKILL_PATH, 'utf-8');
+
+ test('both skills point at the docs site and the source repo', () => {
+ // Assert the angle-bracket autolink form. A bare `toContain(SOURCE_URL)`
+ // passes vacuously off the frontmatter's `repository:` value, which is the
+ // superstring `.../open-knowledge-skills`, so the guard would stay green
+ // with the body link deleted.
+ for (const text of [project, discovery]) {
+ expect(text).toContain(`<${DOCS_URL}>`);
+ expect(text).toContain(`<${SOURCE_URL}>`);
+ }
+ });
+
+ test("discovery skill's description triggers on capability questions", () => {
+ // Anchor to the `description:` key. Skill routing reads that field alone,
+ // so an unanchored match would stay green if the clause moved to
+ // `compatibility:` or `metadata:` while the skill stopped triggering.
+ const frontmatter = discovery.split('---')[1] ?? '';
+ expect(frontmatter).toMatch(/^description:.*supports a particular capability/m);
+ });
+
+ test('capability sections enumerate no individual capability', () => {
+ // Slice from each heading to the next one. Assert the heading was found
+ // first — a missing heading would otherwise slice to nothing and pass the
+ // negative match vacuously.
+ const section = (text: string, heading: string): string => {
+ const start = text.indexOf(heading);
+ expect(start, `heading not found: ${heading}`).toBeGreaterThan(-1);
+ const rest = text.slice(start);
+ const end = rest.indexOf('\n## ', heading.length);
+ const body = end === -1 ? rest : rest.slice(0, end);
+ expect(body.length, `empty section: ${heading}`).toBeGreaterThan(heading.length);
+ return body;
+ };
+
+ for (const body of [
+ section(project, '## Capabilities beyond this skill'),
+ section(discovery, '## What else OK does'),
+ ]) {
+ expect(body).not.toMatch(/OKF|Slidev|themes|network access/i);
+ }
+ });
+});