Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): skill-reference follow-ups from #3855 review (PRD-8283) (#3860)

tim-inkeep3ab979a199b0
diff --git a/.changeset/skill-references-tool-surface.md b/.changeset/skill-references-tool-surface.md
new file mode 100644
index 000000000..6d05a83db
--- /dev/null
+++ b/.changeset/skill-references-tool-surface.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The bundled agent skills now match the MCP tool surface. `links` is called with the parameter names the tool accepts (`document`, `sourceDocuments`), `audit` is named as the end-state check and described by what it actually reports (every lint violation plus every broken internal link, not just dead links), with `links({ kind: "dead" })` as the graph reader and a superset of `audit` on the source side, external images route through the ingest procedure instead of an ad-hoc fetch, and the OKF reserved-file frontmatter exemption is documented. The project skill refreshes on its own. A pack skill already seeded into a project is yours to edit, so it keeps its old text and seeding again will not refresh it; update that skill from source, or delete it and reseed, to pick up the corrected wording.
diff --git a/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md b/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md
index 856c6828e..0a5c78f47 100644
--- a/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md
+++ b/packages/server/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md
@@ -102,10 +102,10 @@ Atomic pages for domain terms and core abstractions (one term each): definition,
### Phase 7 — Link-graph activation + audit
1. Confirm **OVERVIEW links every page** (it is the nav hub). Add any missing nav links. This is OVERVIEW's check — it's a *source* (high out-degree), verified by forward links here, not by the `hubs` view below.
-2. Run `links({ kind: ["orphans", "hubs"] })`, then `audit` for dead links:
+2. Run `links({ kind: ["orphans", "hubs"] })`, then `audit`:
- **orphans** — pages nothing links to. Adopt each by linking it from OVERVIEW or a relevant section page (or, rarely, justify it as intentionally standalone).
- **hubs** — ranks by *inbound* links. Confirm your **concept/module pages** show up here — that's the signal cross-linking actually happened. Don't expect `OVERVIEW`: a freshly authored nav page has almost no inbound links, so it won't appear (and that's correct — its coverage was checked in step 1).
- - **dead** (`audit`) — fix or remove every dead link. (Source-file links don't appear in this graph — only `.md`/`.mdx` edges are tracked — but they ARE validated by `brokenLinks` on each write/edit, per the code-reference rule above.)
+ - **`audit`** — returns clean (every lint violation + broken internal link) — fix every finding. (This covers links to source files too, not just `.md`/`.mdx`: it's the `orphans`/`hubs` graph above that tracks doc-to-doc edges only. `brokenLinks` on each write/edit is the same check per-write, per the code-reference rule above.)
3. Append a `wiki/log.md` entry (see *Log discipline*).
4. Tell the user the wiki is ready and surface the OVERVIEW preview URL.
diff --git a/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md b/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md
index 3cb684253..749015820 100644
--- a/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md
+++ b/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md
@@ -336,7 +336,7 @@ Run this checklist before marking complete:
- File exists at the chosen path under the content directory
- Frontmatter has `title`, `description`, `type: research-note`, `status: draft`, `date`, and an object-shaped `sources:` list
- `exec("ls -A <dir>")` lists the new file with frontmatter enrichment
-- `audit({ path: "<doc-path>.md" })` returns clean — zero dead links (fix or remove every one)
+- `audit({ path: "<doc-path>.md" })` returns clean (every lint violation + broken internal link) — fix every finding
- Every factual claim in Findings cites a source inline
- Linked source files from Step 3 all exist (broken source links → ingest went wrong somewhere)
- At least 1-2 neighbor docs now link to this research (per Step 6's "After writing, update ..." rule)
diff --git a/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md
index 27379357a..3640cd495 100644
--- a/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md
+++ b/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md
@@ -184,7 +184,7 @@ Run before you tell the user it's ready:
- Every referenced decision, spec, or guide is a plain markdown relative link (`[text](./decisions/0004-x.md)`), never backticked, never an HTML anchor.
- Add backlinks from 1–2 closely related docs so the proposal is discoverable — the accepted decision it revisits, a related spec, the relevant guide. `links({ kind: "backlinks", ... })` to see what already points where.
-- `audit({ path: "proposals/0007-async-export-pipeline.md" })` returns clean — fix or remove every dead link.
+- `audit({ path: "proposals/0007-async-export-pipeline.md" })` returns clean (every lint violation + broken internal link) — fix every finding.
- Frontmatter complete: `type: proposal`, a one-line `description`, `status: draft`, `authors`, `created`, `tags: [proposal]`.
- All five H2 sections present and non-empty: `## Motivation`, `## Design`, `## Drawbacks`, `## Alternatives`, `## Unresolved questions`. An empty Drawbacks or a strawman Alternatives fails this check even though the section technically exists.
- `status` is still `draft`. You do not advance it — see Non-goals.
diff --git a/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md
index 4ad6a2766..b3dc6943d 100644
--- a/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md
+++ b/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md
@@ -160,7 +160,7 @@ Then add a line near the top of the old record's Context (or a short `> Supersed
## Step 8 — Link and validate
- **Backlinks in:** ensure the parent proposal links forward to this decision, and any spec that *implements* this decision links back to it. `links({ kind: "backlinks", document: "decisions/0012-adopt-event-sourcing-for-orders" })` to see who points here; add the missing ones so the record is discoverable.
-- **Dead links out:** `audit({ path: "decisions/0012-adopt-event-sourcing-for-orders.md" })` returns clean — zero dead links. Fix or remove every one; a broken link to a superseded record defeats the whole chain.
+- **Validate:** `audit({ path: "decisions/0012-adopt-event-sourcing-for-orders.md" })` returns clean (every lint violation + broken internal link) — fix every finding; a broken link to a superseded record defeats the whole chain.
- **Frontmatter complete:** `type`, `description`, `status`, `date`, `deciders`, `supersedes`, `tags` all present and correct.
- **Status reflects reality:** if the deciders have accepted, flip `status: proposed` → `accepted`. If they haven't, leave it `proposed` and tell the user it's awaiting sign-off. Do not mark a decision `accepted` on the user's behalf.
- **Body shape:** exactly `## Context`, `## Decision`, `## Consequences`, in order. No extra top-level sections — depth that doesn't fit these three belongs in a linked spec.
diff --git a/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md
index b1d735716..8af6d570b 100644
--- a/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md
+++ b/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md
@@ -175,7 +175,7 @@ Pre-fill the stub with the **symptom** (how you'd recognize this again — "chec
- Add a `## Related` section linking **every prior postmortem that shares a subsystem** (from Step 2), plus the `decisions/` and `specs/` implicated — the decision that set the config policy, the spec for the component that failed. `[2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md)`, `[connection-pool sizing decision](./decisions/2023-11-04-pool-sizing.md)`.
- Link the runbook stubs you created in Step 9 from their action items (done above) and from `## Related`.
- Update the hub of any folder you touched if it has one (an `INDEX.md` in `postmortems/`) so the new incident shows up in the index — the preview becomes a live progress bar.
-- Validate: `audit({ path: "postmortems/YYYY-MM-DD-name.md" })` returns clean — fix or drop every dead link. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.
+- Validate: `audit({ path: "postmortems/YYYY-MM-DD-name.md" })` returns clean (every lint violation + broken internal link) — fix every finding. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.
---
diff --git a/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md
index 761441f3b..3d89e8f10 100644
--- a/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md
+++ b/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md
@@ -262,7 +262,7 @@ Specs that don't link back are islands. Wire the spec into the graph and prove i
- **Backlink the parent proposal** inline in the spec body: `derived from [Payment retries proposal](./proposals/0004-payment-retries.md)`. Plain markdown relative link — never backticked, never an HTML anchor.
- **Link every decision the spec depends on** — if the design rests on a frozen record in `decisions/`, link it where it's relied upon.
- Update the parent proposal (and any hub) to link forward to this spec, so the spec is discoverable via backlinks. `links({ kind: "backlinks", ... })` to confirm the reverse edge registered.
-- `audit({ path: "specs/004-payment-retries/spec.md" })` — returns clean, zero dead links. Fix or remove every one.
+- `audit({ path: "specs/004-payment-retries/spec.md" })` returns clean (every lint violation + broken internal link) — fix every finding.
- Frontmatter complete: `type`, `description`, `status`, `owner`, `parent_proposal`, `created`, `tags` all present.
---
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index 7f43655d0..d54c723b4 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -25,7 +25,7 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th
## Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)
-- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`).
+- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`; caveats in `references/linking.md`).
- **Writes** — four native CRUD verbs, polymorphic over `document` / `folder` / `template` / `skill` / `asset` (pass EXACTLY ONE target, nested under its address key): `write` (create/overwrite; `write({ skill: {…} })` authors a skill as a REAL folder at the project's default skill home — live immediately for that folder's agent), `edit` (body find/replace/frontmatter merge-patch; no asset), `delete` (remove), `move` (move/rename, rewrites referrers; a skill also takes `scope`/`toScope` for Project↔Global — history resets, re-`install`). Output mirrors the input key; the preview envelope (`previewUrl`, `warning`) stays top-level. Plus `install` (WHERE a `skill` lives: `add`/`remove` locations additively — editor ids, `agents`, or custom roots; `mode` + `convert` re-form ONLY the locations named; `source` moves the real folder. The source folder IS the skill — no "uninstall everywhere"; a skill dies only via `delete`), `import` (acquire a skill-dir into `add`'s locations; scripts never run), `checkpoint` (named version), and `restore_version` (roll back). A folder's frontmatter is open-shape and self-only (does NOT cascade); templates are what new docs start with.
- **Conflicts** — `conflicts` (`kind: list|content`), `resolve_conflict` (write a resolution + commit; destructive). See `references/conflict-resolution.md`.
diff --git a/packages/server/assets/skills/project/references/linking.md b/packages/server/assets/skills/project/references/linking.md
index f4d71dc3e..fde832dd1 100644
--- a/packages/server/assets/skills/project/references/linking.md
+++ b/packages/server/assets/skills/project/references/linking.md
@@ -10,7 +10,7 @@
- **Never wrap a link in backticks.** `` `[text](./foo.md)` `` is a bug — the backticks make it render as literal code rather than a link.
- **Never use HTML anchors** (`<a href="...">`). Markdown link syntax only.
- **`brokenLinks` on the write/edit response is your primary check — read it before walking away.** Every `write`/`edit` returns `brokenLinks` in the SAME payload: `[]` means every outbound link resolves; a populated list names each broken `href` with its `resolvedTo` + `reason` (`no-such-doc` = resolved to a doc that doesn't exist; `no-such-file` = resolved to a linked asset / source file that isn't on disk at that path; `unresolvable` = the path escapes the content root, usually one `../` too many). This validates **every** local link, not just doc links: a wrong-depth `[src](../../foo.py)` to a source file is caught too. It is report-only — the write landed regardless; fix or remove every one in a follow-up `edit`.
-- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Caveat: `audit` reports links only while the project's `validation.links` setting is not `off` (at `off` it returns clean with no warning), so if the project has silenced link validation, fall back to `links({ kind: "dead" })` — the unconditional read of the same dead-link data (optionally scoped: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`). Otherwise `links` is the graph-navigation reader, supplemental to `audit`, not a substitute. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
+- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Caveat: `audit` reports links only while the project's `validation.links` setting is not `off` (at `off` it returns clean with no warning), so if the project has silenced link validation, fall back to `links({ kind: "dead" })` — the unconditional read of the dead-link graph, which also lists sources `audit` excludes, such as skill-bundle docs (optionally scoped: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`). Otherwise `links` is the graph-navigation reader, supplemental to `audit`, not a substitute. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
- **The tool and the editor agree.** Both resolve a bare name the same way — exact, then slug, then folder index, then basename — so a link that opens when you click it is never reported dead, and a link reported dead is genuinely unresolvable. A target that names an asset, or names nothing at all, stays silent rather than being reported as a broken doc link.
**Note on wiki-link syntax (`[[Page]]`):** the parser still handles it for legacy content, but it's NO LONGER the recommended default. Write new content with standard markdown links per above. Seed-pack templates (`ok seed --pack <name>`) may still emit `[[Page]]` placeholders inside template body text — those are legacy. When you instantiate a seed-pack template, replace the legacy placeholders with standard markdown links during the `{shape}`-fill pass.
diff --git a/packages/server/assets/skills/project/references/onboard-existing-repo.md b/packages/server/assets/skills/project/references/onboard-existing-repo.md
index 4777290d0..01c94759b 100644
--- a/packages/server/assets/skills/project/references/onboard-existing-repo.md
+++ b/packages/server/assets/skills/project/references/onboard-existing-repo.md
@@ -179,7 +179,7 @@ Six sub-passes, each with its own STOP gate.
### 5c. Dead-link sweep (STOP gate 5c)
-1. Run `audit` (the authoritative end-state link check; it covers the whole corpus). `links({ kind: "dead" })` is the graph-navigation view of the same data, useful for browsing but not the validation step.
+1. Run `audit` (the authoritative end-state link check; it covers the whole corpus — caveats in `references/linking.md`). `links({ kind: "dead" })` is the graph reader, not the validation step; it is a superset on the source side (it also lists dead links whose source is a skill-bundle doc, which `audit` skips).
2. For each dead link, propose: a fix candidate (via `search` for the correct target), or deletion (remove the link, or the prose around it). Leaving it as an "intentional redlink" is not an option — every dead link is fixed or removed.
3. Confirm per dead-link. Apply confirmed fixes via `edit`.
diff --git a/packages/server/src/skill-links-params-contract.test.ts b/packages/server/src/skill-links-params-contract.test.ts
index 86327f3ad..93744e602 100644
--- a/packages/server/src/skill-links-params-contract.test.ts
+++ b/packages/server/src/skill-links-params-contract.test.ts
@@ -1,14 +1,22 @@
/**
- * Shipped skill assets must call `links` with parameter names the MCP tool
+ * Shipped skill assets must call `links` / `audit` with parameter names the MCP tool
* actually declares (`docName` / `sourceDocNames` shipped for months
- * and errored or silently audited the whole corpus). The key list mirrors the
- * `inputSchema` in `src/mcp/tools/links.ts` — update both together.
+ * and errored or silently audited the whole corpus). The key lists mirror the
+ * `inputSchema`s in `src/mcp/tools/links.ts` and `src/mcp/tools/audit.ts` — update
+ * all three together.
+ *
+ * Also guards the prose: no shipped skill may frame `audit` as a dead-link-only
+ * check, since it merges lint + links. Wording for the project bundle specifically
+ * is pinned in `skill-linking-contract.test.ts` — keep the two in their own lanes.
*/
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, test } from 'vitest';
-const LINKS_INPUT_KEYS = new Set(['kind', 'document', 'sourceDocuments', 'mode', 'limit', 'cwd']);
+const TOOL_INPUT_KEYS = {
+ links: new Set(['kind', 'document', 'sourceDocuments', 'mode', 'limit', 'cwd']),
+ audit: new Set(['path', 'cwd']),
+};
const SKILLS_DIR = join(import.meta.dirname, '../assets/skills');
function walk(dir: string): string[] {
@@ -18,16 +26,42 @@ function walk(dir: string): string[] {
});
}
-describe('shipped skills call links() with declared parameter names', () => {
+const CALL_RE = /\b(links|audit)\(\{([^}]*)\}\)/g;
+
+describe('shipped skills call links()/audit() with declared parameter names', () => {
+ const callSites = { links: 0, audit: 0 };
for (const file of walk(SKILLS_DIR)) {
const text = readFileSync(file, 'utf-8');
- const calls = [...text.matchAll(/links\(\{([^}]*)\}\)/g)];
+ const calls = [...text.matchAll(CALL_RE)];
if (calls.length === 0) continue;
+ for (const [, tool] of calls) callSites[tool as keyof typeof callSites]++;
test(file.slice(SKILLS_DIR.length + 1), () => {
- for (const [, body] of calls) {
- const keys = [...body.matchAll(/(?:^|,)\s*([A-Za-z_]+)\s*:/g)].map((m) => m[1]);
- for (const key of keys) expect(LINKS_INPUT_KEYS, `links({ ${key}: … })`).toContain(key);
+ expect.hasAssertions();
+ for (const [, tool, body] of calls) {
+ // Matches `key:` and ES2015 shorthand `{ kind, document }`.
+ const keys = [...body.matchAll(/(?:^|,)\s*([A-Za-z_]+)\s*(?=[:,]|$)/g)].map((m) => m[1]);
+ for (const key of keys) {
+ expect(
+ TOOL_INPUT_KEYS[tool as keyof typeof TOOL_INPUT_KEYS],
+ `${tool}({ ${key}: … })`,
+ ).toContain(key);
+ }
}
});
}
+ test('scan is not vacuous', () => {
+ expect(callSites.links).toBeGreaterThan(10);
+ expect(callSites.audit).toBeGreaterThan(3);
+ });
+});
+
+describe('shipped skills describe audit by what it reports', () => {
+ test('no shipped skill frames `audit` as a dead-link-only check', () => {
+ for (const file of walk(SKILLS_DIR)) {
+ const text = readFileSync(file, 'utf-8');
+ for (const stale of ['zero dead links', 'fix or remove every dead link']) {
+ expect(text, `${file.slice(SKILLS_DIR.length + 1)}: ${stale}`).not.toContain(stale);
+ }
+ }
+ });
});