Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdindex 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 arelative path). Re-opening the same file lands on the same session. Neverconstruct 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 oneDo **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.mdindex 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`. **WithoutDon'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 lifecycleIf `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.tsnew file mode 100644index 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);+ }+ });+});