Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdxindex 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.tsindex 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.tsindex 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.tsindex 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 = zscope: 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.mdindex 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 pageopen, 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 notrun `npx skills add` as thedefault install path in this flow: import through OpenKnowledge(`import({ source, skill, add })`) so the skill lands as a real folder withdiff --git a/packages/server/src/mcp/tools/import.ts b/packages/server/src/mcp/tools/import.tsindex 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: zdiff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.tsindex 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({