Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): group repo-declared plugin skills in every checkout (PRD-8261) (#3840)

tim-inkeepcdc92d752c87
diff --git a/.changeset/prd-8261-repo-marketplace-plugin-groups.md b/.changeset/prd-8261-repo-marketplace-plugin-groups.md
new file mode 100644
index 000000000..0385ffb60
--- /dev/null
+++ b/.changeset/prd-8261-repo-marketplace-plugin-groups.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Skills served by a plugin the repo itself declares (a `.claude-plugin/marketplace.json` with in-tree plugin sources) now group under that plugin in every checkout of the repo. Grouping previously depended on the editor's plugin registry, which records installs per absolute path, so a second clone of the same repo showed those skills as a flat, ungrouped list. The repo manifest is now read directly, so the identity no longer depends on where the clone lives or whether the editor has registered it.
diff --git a/packages/app/tests/integration/skills-in-place-list.test.ts b/packages/app/tests/integration/skills-in-place-list.test.ts
index 068df1a08..9f9ef72f4 100644
--- a/packages/app/tests/integration/skills-in-place-list.test.ts
+++ b/packages/app/tests/integration/skills-in-place-list.test.ts
@@ -1,4 +1,12 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
@@ -1568,3 +1576,51 @@ describe('outsideProject stamp on /api/skills/installed', () => {
expect(found?.outsideProject).toBe(true);
});
});
+
+describe('repo-declared plugin identity on /api/skills (no harness registry)', () => {
+ let contentDir: string;
+ let server: TestServer;
+
+ beforeEach(async () => {
+ contentDir = mkdtempSync(join(tmpdir(), 'ok-repo-plugin-'));
+ mkdirSync(join(contentDir, '.claude-plugin'), { recursive: true });
+ writeFileSync(
+ join(contentDir, '.claude-plugin', 'marketplace.json'),
+ JSON.stringify({ name: 'repo-mkt', plugins: [{ name: 'tools', source: './plugins/tools' }] }),
+ );
+ mkdirSync(join(contentDir, '.claude'), { recursive: true });
+ writeFileSync(
+ join(contentDir, '.claude', 'settings.json'),
+ JSON.stringify({ enabledPlugins: { 'tools@repo-mkt': true } }),
+ );
+ mkdirSync(join(contentDir, 'plugins/tools/.claude-plugin'), { recursive: true });
+ writeFileSync(
+ join(contentDir, 'plugins/tools/.claude-plugin/plugin.json'),
+ JSON.stringify({ name: 'tools', repository: 'https://github.com/acme/tools' }),
+ );
+ writeSkill(contentDir, 'plugins/tools/skills/served', '# Served by the plugin');
+ mkdirSync(join(contentDir, '.agents/skills'), { recursive: true });
+ symlinkSync('../../plugins/tools/skills/served', join(contentDir, '.agents/skills/served'));
+ writeSkill(contentDir, '.agents/skills/handmade', '# Hand-authored');
+ server = await createTestServer({ contentDir });
+ });
+ afterEach(async () => {
+ await server.cleanup();
+ rmSync(contentDir, { recursive: true, force: true });
+ });
+
+ test('a symlinked in-repo plugin skill carries the plugin; a hand-authored sibling does not', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/skills?scope=project`);
+ expect(res.status).toBe(200);
+ const { skills } = (await res.json()) as {
+ skills: Array<{ name: string; plugin?: Record<string, unknown> }>;
+ };
+ expect(skills.find((s) => s.name === 'served')?.plugin).toEqual({
+ name: 'tools',
+ marketplace: 'repo-mkt',
+ provider: 'claude',
+ url: 'https://github.com/acme/tools',
+ });
+ expect(skills.find((s) => s.name === 'handmade')?.plugin).toBeUndefined();
+ });
+});
diff --git a/packages/core/src/skills-catalog/index.ts b/packages/core/src/skills-catalog/index.ts
index 7bf41a5c1..7299175af 100644
--- a/packages/core/src/skills-catalog/index.ts
+++ b/packages/core/src/skills-catalog/index.ts
@@ -94,6 +94,11 @@ export type {
} from './plugin-providers/types.ts';
export { type PluginUpstream, pluginUpstreamsByName } from './plugin-upstream.ts';
export { parseSkillsShPublisherPage } from './publisher.ts';
+export {
+ type RepoMarketplacePlugin,
+ readRepoMarketplacePlugins,
+ repoMarketplacePluginFor,
+} from './repo-marketplace.ts';
export { parseGitHubRepoSearch, parseOpenGraph, parseSkillsShSearch } from './search.ts';
export {
buildSkillRegistry,
diff --git a/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts b/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts
index 0ae8c4db5..c7be32f1b 100644
--- a/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts
+++ b/packages/core/src/skills-catalog/plugin-providers/manifest-providers.ts
@@ -149,7 +149,7 @@ export function enumerateAgentPluginsRoot(
}
/** The manifest's optional `repository` URL, or null. */
-function manifestRepositoryUrl(dir: string, rel: string): string | null {
+export function manifestRepositoryUrl(dir: string, rel: string): string | null {
try {
const parsed = JSON.parse(readFileSync(join(dir, rel), 'utf-8')) as { repository?: unknown };
return typeof parsed.repository === 'string' && parsed.repository.length > 0
diff --git a/packages/core/src/skills-catalog/plugin-upstream.ts b/packages/core/src/skills-catalog/plugin-upstream.ts
index f4cfd730a..1e512b354 100644
--- a/packages/core/src/skills-catalog/plugin-upstream.ts
+++ b/packages/core/src/skills-catalog/plugin-upstream.ts
@@ -44,9 +44,16 @@ export interface PluginUpstream {
* their copies are already first-class rows elsewhere — treating one as an
* upstream would let a skill become its own origin.
*
- * First writer wins for a duplicated name, matching the order the detected list
- * itself resolves duplicates in, so the two surfaces cannot disagree about which
- * plugin owns a name.
+ * First writer wins for a duplicated name. The `/api/skills` index is built from
+ * the machine-wide enumeration (a copy of a plugin's skill is that plugin's
+ * wherever the copy sits, and the registry keys project installs by checkout
+ * path), while `/api/skills/installed` stays project-scoped, so name-only
+ * consumers may resolve a different plugin for a name than the detected list
+ * would. That covers more than the Modified badge: the synthesized lock entry's
+ * source is the plugin cache dir, and a reimport fetches from it, so a name
+ * collision across project-scoped plugins on one machine could overwrite a
+ * hand-authored skill in another project on an explicit reimport. The
+ * realpath-verified identity path is unaffected.
*/
export function pluginUpstreamsByName(
skills: readonly CatalogSkill[],
diff --git a/packages/core/src/skills-catalog/repo-marketplace.test.ts b/packages/core/src/skills-catalog/repo-marketplace.test.ts
new file mode 100644
index 000000000..6bbb7e679
--- /dev/null
+++ b/packages/core/src/skills-catalog/repo-marketplace.test.ts
@@ -0,0 +1,105 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readRepoMarketplacePlugins, repoMarketplacePluginFor } from './repo-marketplace.ts';
+
+let repo: string;
+
+beforeEach(() => {
+ repo = mkdtempSync(join(tmpdir(), 'ok-repo-marketplace-'));
+ mkdirSync(join(repo, '.claude-plugin'));
+ writeFileSync(
+ join(repo, '.claude-plugin', 'marketplace.json'),
+ JSON.stringify({
+ name: 'inkeep-agents-private',
+ plugins: [
+ { name: 'agents', source: './public/agents/plugins/agents' },
+ { name: 'remote', source: 'github:foo/bar' },
+ { name: 'missing', source: './nowhere' },
+ // Resolves on disk, so only the in-tree guard can exclude it.
+ { name: 'absolute', source: join(repo, 'public/agents/plugins/agents') },
+ // Declared and on disk, but the repo does not enable it.
+ { name: 'disabled', source: './public/agents/plugins/agents' },
+ // Enabled but the dir is gone (uninitialized submodule, mid-rename).
+ { name: 'phantom', source: './phantom' },
+ // Relative, but climbs out of the tree.
+ { name: 'escape', source: '../outside-plugin' },
+ ],
+ }),
+ );
+ mkdirSync(join(repo, '.claude'));
+ writeFileSync(
+ join(repo, '.claude', 'settings.json'),
+ JSON.stringify({
+ enabledPlugins: {
+ 'agents@inkeep-agents-private': true,
+ 'absolute@inkeep-agents-private': true,
+ 'disabled@inkeep-agents-private': false,
+ 'phantom@inkeep-agents-private': true,
+ 'escape@inkeep-agents-private': true,
+ },
+ }),
+ );
+ mkdirSync(join(repo, 'public/agents/plugins/agents/.claude-plugin'), { recursive: true });
+ writeFileSync(
+ join(repo, 'public/agents/plugins/agents/.claude-plugin/plugin.json'),
+ JSON.stringify({ name: 'agents', repository: 'https://github.com/inkeep/agents-private' }),
+ );
+ mkdirSync(join(repo, 'public/agents/plugins/agents/skills/write-docs'), { recursive: true });
+ mkdirSync(join(repo, 'public/agents/plugins/agents/references/not-a-skill'), { recursive: true });
+ mkdirSync(join(repo, '.agents/skills'), { recursive: true });
+ symlinkSync(
+ '../../public/agents/plugins/agents/skills/write-docs',
+ join(repo, '.agents/skills/write-docs'),
+ );
+ mkdirSync(join(repo, '.agents/skills/hand-authored'));
+ mkdirSync(join(repo, '..', 'outside-plugin', 'skills'), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(repo, { recursive: true, force: true });
+ rmSync(join(repo, '..', 'outside-plugin'), { recursive: true, force: true });
+});
+
+describe('repo-declared marketplace plugins', () => {
+ it('keeps only in-tree, enabled plugin roots, with the plugin.json repository as url', () => {
+ const plugins = readRepoMarketplacePlugins(repo);
+ expect(plugins.map((p) => p.name)).toEqual(['agents']);
+ expect(plugins[0]).toMatchObject({
+ marketplace: 'inkeep-agents-private',
+ url: 'https://github.com/inkeep/agents-private',
+ });
+ });
+
+ it('identifies a symlinked in-repo plugin skill; leaves a hand-authored one alone', () => {
+ const plugins = readRepoMarketplacePlugins(repo);
+ expect(repoMarketplacePluginFor(plugins, join(repo, '.agents/skills/write-docs'))?.name).toBe(
+ 'agents',
+ );
+ expect(
+ repoMarketplacePluginFor(plugins, join(repo, '.agents/skills/hand-authored')),
+ ).toBeNull();
+ expect(repoMarketplacePluginFor(plugins, join(repo, '.agents/skills/gone'))).toBeNull();
+ expect(
+ repoMarketplacePluginFor(
+ plugins,
+ join(repo, 'public/agents/plugins/agents/references/not-a-skill'),
+ ),
+ ).toBeNull();
+ });
+
+ it('is empty without a manifest, and without enabledPlugins', () => {
+ expect(readRepoMarketplacePlugins(join(repo, 'public'))).toEqual([]);
+ rmSync(join(repo, '.claude', 'settings.json'));
+ expect(readRepoMarketplacePlugins(repo)).toEqual([]);
+ });
+
+ it('warns on a malformed manifest instead of treating it as absent', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ writeFileSync(join(repo, '.claude-plugin', 'marketplace.json'), '{ not json');
+ expect(readRepoMarketplacePlugins(repo)).toEqual([]);
+ expect(warn).toHaveBeenCalledTimes(1);
+ warn.mockRestore();
+ });
+});
diff --git a/packages/core/src/skills-catalog/repo-marketplace.ts b/packages/core/src/skills-catalog/repo-marketplace.ts
new file mode 100644
index 000000000..680e13c5a
--- /dev/null
+++ b/packages/core/src/skills-catalog/repo-marketplace.ts
@@ -0,0 +1,112 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { manifestRepositoryUrl } from './plugin-providers/manifest-providers.ts';
+
+/** A plugin the open repo itself declares, resolved to its on-disk root. */
+export interface RepoMarketplacePlugin {
+ readonly name: string;
+ readonly marketplace: string;
+ /** Realpath of the plugin's root dir; skills live at `<root>/skills/<name>`. */
+ readonly rootReal: string;
+ readonly url?: string;
+}
+
+/**
+ * Plugins declared by the open tree's own `.claude-plugin/marketplace.json`.
+ *
+ * A repo that hosts its marketplace serves these plugins in place, so a skill
+ * under one of their roots IS the plugin's skill regardless of whether the
+ * user's harness registry knows about this checkout. The registry is keyed by
+ * absolute path: a second clone of the same repo has no entries there, the
+ * identity join through `enumerateInstalledSkills` comes up empty, and every
+ * in-repo plugin skill read as hand-authored. The manifest is the authority the
+ * registry was only echoing, so read it directly.
+ *
+ * Only relative (in-tree) `source` entries count; a marketplace entry pointing
+ * at a remote or absolute source is not served from this tree. And only plugins
+ * the repo ENABLES count: the identity feeds a "Claude already loads this via
+ * the plugin" claim downstream, and declaring a plugin does not make a harness
+ * load it — `.claude/settings.json` `enabledPlugins` does.
+ */
+export function readRepoMarketplacePlugins(contentDir: string): RepoMarketplacePlugin[] {
+ let manifest: { name?: unknown; plugins?: Array<{ name?: unknown; source?: unknown }> };
+ try {
+ manifest = JSON.parse(
+ readFileSync(join(contentDir, '.claude-plugin', 'marketplace.json'), 'utf-8'),
+ );
+ } catch (err) {
+ warnUnlessMissing(err, 'failed to read repo marketplace manifest, skipping', contentDir);
+ return [];
+ }
+ if (typeof manifest?.name !== 'string' || !Array.isArray(manifest.plugins)) return [];
+ let contentReal: string;
+ try {
+ contentReal = realpathSync(contentDir);
+ } catch (err) {
+ warnUnlessMissing(err, 'failed to resolve the content dir, skipping repo plugins', contentDir);
+ return [];
+ }
+ const enabled = readEnabledPlugins(contentDir);
+ const out: RepoMarketplacePlugin[] = [];
+ for (const p of manifest.plugins) {
+ if (typeof p?.name !== 'string' || typeof p?.source !== 'string') continue;
+ if (isAbsolute(p.source) || /^[a-z]+:/i.test(p.source)) continue;
+ if (enabled[`${p.name}@${manifest.name}`] !== true) continue;
+ let rootReal: string;
+ try {
+ rootReal = realpathSync(resolve(contentDir, p.source));
+ } catch (err) {
+ // ENOENT is the phantom case (uninitialized submodule, mid-rename) and stays quiet.
+ warnUnlessMissing(err, `failed to resolve plugin root for ${p.name}, skipping`, contentDir);
+ continue;
+ }
+ // A relative source can still climb out (`../sibling`); that dir is not this tree's.
+ if (!rootReal.startsWith(`${contentReal}${sep}`)) continue;
+ // No plugin.json is fine: the marketplace entry alone is enough for identity.
+ const url = manifestRepositoryUrl(rootReal, '.claude-plugin/plugin.json');
+ out.push({ name: p.name, marketplace: manifest.name, rootReal, ...(url ? { url } : {}) });
+ }
+ return out;
+}
+
+/** An absent file is the common case and stays silent; a malformed or unreadable
+ * one silently zeroes out every repo plugin, so it gets a warning an operator can
+ * tell apart from "nothing declared" (same posture as the enumerator). */
+function warnUnlessMissing(err: unknown, msg: string, contentDir: string): void {
+ if ((err as NodeJS.ErrnoException | null)?.code === 'ENOENT') return;
+ console.warn(`[skills-catalog] ${msg}`, { contentDir, err });
+}
+
+/** `enabledPlugins` from the repo's shared `.claude/settings.json`; `{}` when absent or unreadable. */
+function readEnabledPlugins(contentDir: string): Record<string, unknown> {
+ try {
+ const settings = JSON.parse(
+ readFileSync(join(contentDir, '.claude', 'settings.json'), 'utf-8'),
+ ) as { enabledPlugins?: unknown };
+ const e = settings.enabledPlugins;
+ return e && typeof e === 'object' ? (e as Record<string, unknown>) : {};
+ } catch (err) {
+ warnUnlessMissing(
+ err,
+ 'failed to read .claude/settings.json, no repo plugins enabled',
+ contentDir,
+ );
+ return {};
+ }
+}
+
+/** The repo-declared plugin whose `skills/` dir holds `skillAbsDir` (symlinks resolved), or null. */
+export function repoMarketplacePluginFor(
+ plugins: readonly RepoMarketplacePlugin[],
+ skillAbsDir: string,
+): RepoMarketplacePlugin | null {
+ if (plugins.length === 0) return null;
+ let real: string;
+ try {
+ real = realpathSync(skillAbsDir);
+ } catch (err) {
+ warnUnlessMissing(err, 'failed to resolve skill dir', skillAbsDir);
+ return null;
+ }
+ return plugins.find((p) => real.startsWith(`${p.rootReal}${sep}skills${sep}`)) ?? null;
+}
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index ea1531abc..4936ff171 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -290,8 +290,10 @@ import {
parseSource,
pluginRepositoryUrl,
pluginUpstreamsByName,
+ readRepoMarketplacePlugins,
readSkillDirMeta,
readWellKnownIndex,
+ repoMarketplacePluginFor,
resolvePluginUpdateSource,
resolveSkillsShImportSource,
retrofitPackLockEntry,
@@ -14368,11 +14370,14 @@ export function createApiExtension(
try {
// Enumeration and hashing are the IO; the join itself is pure and lives in
// core, where it can be tested without a plugin cache on disk.
+ // Deliberately NOT scoped to the project: a copy of a plugin's skill is a
+ // copy of that plugin wherever the copy sits, and the registry keys
+ // project-scoped installs by absolute checkout path, so scoping left a
+ // second clone of the same repo with no upstream for any of its copies.
byName = pluginUpstreamsByName(
- enumerateInstalledSkillsCached({
- projectDir: identity,
- ...(homeDirOverride !== undefined ? { home: homeDirOverride } : {}),
- }).skills,
+ enumerateInstalledSkillsCached(
+ homeDirOverride !== undefined ? { home: homeDirOverride } : {},
+ ).skills,
(home) => parseSkillDir(home)?.contentHash,
);
} catch (err) {
@@ -15162,6 +15167,22 @@ export function createApiExtension(
// read as untracked. Attributing it to every same-named row would put a
// Revert button on a skill whose baseline belongs to a different one.
const projectNameSeen = new Set<string>();
+ // The repo's own marketplace manifest is the second identity source:
+ // the registry join above is keyed by absolute checkout path, so a
+ // second clone of the same repo has no records there and its in-repo
+ // plugin skills would read as hand-authored.
+ const repoPlugins = readRepoMarketplacePlugins(contentDir);
+ const repoPluginIdentity = (dir: string) => {
+ const p = repoMarketplacePluginFor(repoPlugins, dir);
+ return p
+ ? {
+ name: p.name,
+ marketplace: p.marketplace,
+ provider: 'claude',
+ ...(p.url ? { url: p.url } : {}),
+ }
+ : null;
+ };
const inPlace = projectDir
? scanInPlaceSkills(contentDir).map((s) => {
const tracked = !projectNameSeen.has(s.name);
@@ -15176,7 +15197,8 @@ export function createApiExtension(
// Identity beats provenance: a skill that IS a plugin's skill
// carries the plugin, never an origin.
const selfPlugin = tracked
- ? pluginSelfIdentity(s.name, detectedIdentity, skillAbsDir)
+ ? (pluginSelfIdentity(s.name, detectedIdentity, skillAbsDir) ??
+ repoPluginIdentity(skillAbsDir))
: null;
const entry =
tracked && selfPlugin === null
@@ -15311,7 +15333,8 @@ export function createApiExtension(
if (!tracked) return {};
// Same two synthesized fallbacks as the project site: a built-in
// carries its skills.sh origin, a copy of a plugin's skill carries
- // the plugin.
+ // the plugin. The repo-manifest identity is project-only: a global
+ // skill is not tree-local, so no repo can serve it in place.
const globalAbsDir = resolve(skillsHome, s.dir);
const selfPluginGlobal = pluginSelfIdentity(s.name, detectedIdentity, globalAbsDir);
if (selfPluginGlobal !== null) return { plugin: selfPluginGlobal };