Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): correct skills.sh page URLs and the write tool's bundle-path docs (#3088)

tim-inkeep88933bfc916f
diff --git a/.changeset/olive-hounds-repeat.md b/.changeset/olive-hounds-repeat.md
new file mode 100644
index 000000000..6ce2e9e93
--- /dev/null
+++ b/.changeset/olive-hounds-repeat.md
@@ -0,0 +1,9 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix the skills.sh page link on imported skills, and correct the `write` tool's skill bundle-path description.
+
+The provenance link in the Skills UI built its skills.sh URL as `/<publisher>/skills/<skill>`, but that path's middle segment is the source repo, not a literal `skills`. It resolved only for publishers who happen to name their repo `skills`; for everyone else it pointed at a page for a repo that doesn't exist. skills.sh answers those with a placeholder stub rather than a 404, so the link looked fine and quietly showed the wrong skill. It now derives from the recorded source via `skillsShSkillLinks`, which also covers website-catalog sources (`/site/<hostname>/<skill>`). Same correction applied to the `import` tool's `source` docs and the `open-knowledge-write-skill` guide.
+
+The `write` tool advertised skill bundle files as accepting "any path — `references/**`, `scripts/**`, `assets/**`, …", but only `references/` and `scripts/` are accepted; anything else is rejected. An agent following the description got an error contradicting it.
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index 9da7e3c24..e41730c91 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -32,7 +32,7 @@ To point an MCP client at this server, locally or over a tunnel from another mac
| `delete` | Delete a `document` (one path or an array), `folder`, `template`, `skill`, or `asset` |
| `move` | Move or rename a `document`, `folder`, `asset`, `template`, or `skill`, rewriting every affected link (templates and skills carry no inbound links). A skill also moves between Project and Global scope via `scope` + `toScope`: history does not transfer, and you re-establish its editor locations with `install` |
| `install` | Manage **where** a skill is available. A skill is one real folder (its source, which itself loads) plus managed copies/symlinks at other locations — there is no draft state and no "uninstall everywhere". `add` / `remove` change the other locations (editor ids, `agents`, or custom root paths); `mode` flips an editor copy↔symlink; `source` relocates the real folder. To make a skill stop existing, use `delete` |
-| `import` | Acquire a skill from a full skills.sh skill-page URL (`https://www.skills.sh/<publisher>/skills/<skill>`), `owner/repo[/subpath]`, a git URL, or a local / `file://` path into the vendor-neutral `.agents/skills/<name>/` hub as versioned content — live immediately, with cross-harness projection via `install`. Use `skill` to choose one skill from a multi-skill source or a `skills({ query })` result. Records provenance in `.ok/skills-lock.json`; a name collision lands under `<name>-imported`; scripts are imported as content and never executed |
+| `import` | Acquire a skill from a full skills.sh skill-page URL (`https://www.skills.sh/<owner>/<repo>/<skill>`, or `https://www.skills.sh/site/<hostname>/<skill>` for a website catalog), `owner/repo[/subpath]`, a git URL, or a local / `file://` path into the vendor-neutral `.agents/skills/<name>/` hub as versioned content — live immediately, with cross-harness projection via `install`. Use `skill` to choose one skill from a multi-skill source or a `skills({ query })` result. Records provenance in `.ok/skills-lock.json`; a name collision lands under `<name>-imported`; scripts are imported as content and never executed |
| `checkpoint` | Save a project-wide version snapshot — a single restore point. Returns its `version` |
| `restore_version` | Restore one `document` or `skill` to a historical `version` (the SHA from `history` or `checkpoint`) |
| `conflicts` | Read GitHub-sync merge conflicts. `kind: "list"` enumerates tracked conflicts; `kind: "content"` returns one file's base / ours / theirs stages |
diff --git a/packages/app/src/hooks/use-skill-origin.test.ts b/packages/app/src/hooks/use-skill-origin.test.ts
index 6034c3bd0..7495f8f80 100644
--- a/packages/app/src/hooks/use-skill-origin.test.ts
+++ b/packages/app/src/hooks/use-skill-origin.test.ts
@@ -50,6 +50,47 @@ describe('skillOriginUrl', () => {
),
).toBe('https://github.com/acme/ponytail-plugin');
});
+
+ // The skills.sh path's middle segment is the REPO. Hardcoding a literal
+ // `skills` there resolved for publishers who happen to name their repo that
+ // and silently mis-linked everyone else — skills.sh answers 200 with a
+ // placeholder stub for an unknown owner/repo/slug, so nothing surfaced.
+ test('builds the skills.sh page URL from the source repo, not a literal "skills"', () => {
+ expect(
+ skillOriginUrl(
+ {
+ source: 'inkeep/open-knowledge-skills',
+ publisher: 'inkeep',
+ skill: 'open-knowledge-discovery',
+ importedAt: '2026-07-30T12:00:00.000Z',
+ },
+ 'open-knowledge-discovery',
+ ),
+ ).toBe('https://www.skills.sh/inkeep/open-knowledge-skills/open-knowledge-discovery');
+ });
+
+ test('uses the /site/ shape for a website-catalog source', () => {
+ expect(
+ skillOriginUrl(
+ {
+ source: 'open.feishu.cn',
+ publisher: 'open.feishu.cn',
+ skill: 'lark-attendance',
+ importedAt: '2026-07-30T12:00:00.000Z',
+ },
+ 'lark-attendance',
+ ),
+ ).toBe('https://www.skills.sh/site/open.feishu.cn/lark-attendance');
+ });
+
+ test('falls back to the GitHub repo when the import recorded no publisher', () => {
+ expect(
+ skillOriginUrl(
+ { source: 'acme/toolkit', importedAt: '2026-07-30T12:00:00.000Z' },
+ 'widget-audit',
+ ),
+ ).toBe('https://github.com/acme/toolkit');
+ });
});
describe('skillAutoUpdateEnabled', () => {
diff --git a/packages/app/src/hooks/use-skill-origin.ts b/packages/app/src/hooks/use-skill-origin.ts
index a1c464a96..4e4cd5b6e 100644
--- a/packages/app/src/hooks/use-skill-origin.ts
+++ b/packages/app/src/hooks/use-skill-origin.ts
@@ -1,4 +1,4 @@
-import type { SkillOrigin, SkillScope } from '@inkeep/open-knowledge-core';
+import { type SkillOrigin, type SkillScope, skillsShSkillLinks } from '@inkeep/open-knowledge-core';
import { useLingui } from '@lingui/react/macro';
import { useEffect, useState } from 'react';
import { toast } from 'sonner';
@@ -12,11 +12,16 @@ import { reimportSkill, revertSkill } from '@/lib/skills-api';
* URLs return null (the source string is still shown, just not linked).
*/
/** skills.sh page URL when the import recorded a publisher; the slug falls
- * back to the local name (they match unless the source folder was renamed). */
+ * back to the local name (they match unless the source folder was renamed).
+ *
+ * The path's middle segment is the REPO, not a literal `skills` — building it
+ * by hand produced a valid-looking page for every publisher whose repo is named
+ * anything else, because skills.sh renders a placeholder stub (HTTP 200) rather
+ * than 404ing an unknown owner/repo/slug. `skillsShSkillLinks` derives it from
+ * the recorded source and handles the website-catalog (`/site/<host>/…`) shape. */
function skillsShUrl(origin: SkillOrigin, localName: string): string | null {
if (!origin.publisher) return null;
- const slug = origin.skill ?? localName;
- return `https://www.skills.sh/${encodeURIComponent(origin.publisher)}/skills/${encodeURIComponent(slug)}`;
+ return skillsShSkillLinks(origin.source, origin.skill ?? localName)?.skillsUrl ?? null;
}
export function githubUrl(source: string): string | null {
diff --git a/packages/core/src/schemas/api/tags-search.ts b/packages/core/src/schemas/api/tags-search.ts
index 1b7c51e54..ec4199dba 100644
--- a/packages/core/src/schemas/api/tags-search.ts
+++ b/packages/core/src/schemas/api/tags-search.ts
@@ -1519,7 +1519,7 @@ export const SkillImportRequestSchema = z
scope: SkillScopeSchema.default('project'),
source: z.string().min(1).meta({
description:
- 'External skill source: full skills.sh skill-page URL (https://www.skills.sh/<publisher>/skills/<skill>), GitHub owner/repo[/subpath], git URL, or local/file path.',
+ 'External skill source: full skills.sh skill-page URL (https://www.skills.sh/<owner>/<repo>/<skill>, or https://www.skills.sh/site/<hostname>/<skill> for a website catalog), GitHub owner/repo[/subpath], git URL, or local/file path.',
}),
skill: z
.string()
diff --git a/packages/server/assets/skills/write-skill/SKILL.md b/packages/server/assets/skills/write-skill/SKILL.md
index d54ef1545..237508ee3 100644
--- a/packages/server/assets/skills/write-skill/SKILL.md
+++ b/packages/server/assets/skills/write-skill/SKILL.md
@@ -33,7 +33,8 @@ it only if reuse is the right call. Use the Vercel `find-skills` skill,
`npx skills find <query>`, or manual skills.sh search only when the OK MCP
`skills({ query })` path is unavailable. If the user already has a skills.sh page
open, pass the full skill-page URL as `source`, e.g.
-`import({ source: "https://www.skills.sh/<publisher>/skills/<skill>", add: [...] })`. Do not
+`import({ source: "https://www.skills.sh/<owner>/<repo>/<skill>", add: [...] })` — the
+middle segment is the REPO, not a literal `skills`. Do not
run `npx skills add` as the
default install path in this flow: import through OpenKnowledge
(`import({ source, skill, add })`) so the skill lands as a real folder with
diff --git a/packages/server/src/mcp/tools/import.ts b/packages/server/src/mcp/tools/import.ts
index e253e8592..041ac94e9 100644
--- a/packages/server/src/mcp/tools/import.ts
+++ b/packages/server/src/mcp/tools/import.ts
@@ -36,7 +36,7 @@ const DESCRIPTION = [
'Fetches an agentskills.io / skills.sh skill-dir from a `source` and writes it into the vendor-neutral `.agents/skills/<name>/` hub — where it gains history, search, attribution, and cross-harness projection (via `install`) for free. Provenance (source, commit, content hash, publisher) is recorded in `.ok/skills-lock.json`. Scripts are imported as content and are NEVER executed. `add` says where it goes — an import always places the skill somewhere, so `install` afterwards is only for changing WHERE it lives (add/remove/convert/source).',
'',
'**Parameters:**',
- '- `source` — paste the full skills.sh skill-page URL (`https://www.skills.sh/<publisher>/skills/<skill>`), or pass `owner/repo[/subpath]` (GitHub), a git URL, or a local / `file://` path.',
+ '- `source` — paste the full skills.sh skill-page URL (`https://www.skills.sh/<owner>/<repo>/<skill>`, or `https://www.skills.sh/site/<hostname>/<skill>` for a website catalog), or pass `owner/repo[/subpath]` (GitHub), a git URL, or a local / `file://` path.',
'- `skill` — Pick ONE skill when the source bundles several.',
'- `scope` — `project` (default, versioned + shared) or `global` (user-global, unversioned).',
'',
@@ -60,7 +60,7 @@ export function register(server: ServerInstance, deps: ImportDeps): void {
.string()
.min(1)
.describe(
- 'Full skills.sh skill-page URL (`https://www.skills.sh/<publisher>/skills/<skill>`), `owner/repo[/subpath]`, a git URL, or a local / `file://` path.',
+ 'Full skills.sh skill-page URL (`https://www.skills.sh/<owner>/<repo>/<skill>`, or `https://www.skills.sh/site/<hostname>/<skill>` for a website catalog), `owner/repo[/subpath]`, a git URL, or a local / `file://` path.',
),
skill: z.string().min(1).optional().describe('Pick one skill from a multi-skill source.'),
add: z
diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.ts
index a99188247..4e2f8eb05 100644
--- a/packages/server/src/mcp/tools/write.ts
+++ b/packages/server/src/mcp/tools/write.ts
@@ -946,7 +946,7 @@ export function register(server: ServerInstance, deps: WriteDeps): void {
})
.optional()
.describe(
- 'Create or overwrite an agent SKILL bundle (a NEW skill lands at the project\'s default skill home, e.g. `.agents/skills/<name>/`). SKILL.md is authored via `description`+`body`; bundle files (any path — `references/**`, `scripts/**`, `assets/**`, …) via the `files` array. Example: { skill: { name: "trip-log", description: "Use when logging a fishing trip.", body: "# Steps\\n...", files: [{ path: "references/gear.md", content: "..." }] } }',
+ 'Create or overwrite an agent SKILL bundle (a NEW skill lands at the project\'s default skill home, e.g. `.agents/skills/<name>/`). SKILL.md is authored via `description`+`body`; bundle files (under `references/**` or `scripts/**` — no other root is accepted) via the `files` array. Example: { skill: { name: "trip-log", description: "Use when logging a fishing trip.", body: "# Steps\\n...", files: [{ path: "references/gear.md", content: "..." }] } }',
),
asset: z
.object({