Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(mcp): overlay context-mill omnibus skills on the learn catalog (#127815)

Adam Bowkere1941b2c3eca
diff --git a/docs/published/handbook/engineering/ai/writing-skills.md b/docs/published/handbook/engineering/ai/writing-skills.md
index bf091ad7b562..91a96a5abb54 100644
--- a/docs/published/handbook/engineering/ai/writing-skills.md
+++ b/docs/published/handbook/engineering/ai/writing-skills.md
@@ -442,7 +442,7 @@ This repo is not the only source of shipped skills.
[`PostHog/context-mill`](https://github.com/PostHog/context-mill) assembles the "omnibus" skills
from posthog.com docs and publishes them as `skills-mcp-resources.zip`:
`instrument-integration`, `instrument-product-analytics`, `instrument-feature-flags`,
-`instrument-error-tracking`, `instrument-llm-analytics`, `instrument-logs`, and `instrument-metrics`.
+`instrument-error-tracking`, `instrument-llm-analytics`, `instrument-logs`, `instrument-metrics`, and `instrument-tracing`.
These are the skills behind PostHog Desktop's setup buttons and the wizard.
Every consumer below unzips `dist/skills.zip` first and then unzips context-mill on top,
@@ -451,9 +451,17 @@ A same-named skill added here would have its `SKILL.md` overwritten
while its extra reference files survived as orphans in the other source's directory.
The Desktop harness bundle is the exception: it packages context-mill alone,
so a skill from this repo is absent there rather than overwritten.
+The MCP server's `learn` catalog overlays them at runtime:
+the context-mill resource refresh repacks the omnibus skills from the release it already downloads,
+and the skill catalog service merges that copy over `skills.zip` on its next poll,
+keeping the product skill when a name collides and serving no overlay on a pinned archive.
+`learn -s` scores an omnibus skill by its name, description, and `SKILL.md` only,
+because its references are docs snapshots that would crowd out workflow skills;
+`learn posthog:<skill> <path>` still reads any reference.
| Consumer | Merge site |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| MCP server `learn` catalog | `services/mcp/src/hono/skill-catalog-service.ts` – overlays the copy `ContextMillResourceCache` publishes to Redis |
| PostHog Desktop build | `products/desktop/apps/code/vite-main-plugins.mts` (`copyPosthogPlugin`) |
| PostHog Desktop runtime, every 30 min | `products/desktop/packages/workspace-server/src/services/posthog-plugin/update-skills-saga.ts` |
| Desktop harness bundle | `packages/agent/packages/harness/tsup.config.ts` – context-mill only, this repo's skills are absent rather than overwritten |
diff --git a/products/feature_flags/skills/README.md b/products/feature_flags/skills/README.md
index 206b940d7da2..a93b52ee2782 100644
--- a/products/feature_flags/skills/README.md
+++ b/products/feature_flags/skills/README.md
@@ -38,7 +38,7 @@ So:
- **Do not add a second skill covering the same trigger**, for example `wrapping-code-in-feature-flags`.
Two entry points for one job means agents pick one at random and the two drift.
A rename needs an atomic rename and migration agreed with the skills-distribution owner.
-- The same applies to the other six omnibus skills: `instrument-integration`, `instrument-product-analytics`, `instrument-error-tracking`, `instrument-llm-analytics`, `instrument-logs`, and `instrument-metrics`.
+- The same applies to the other seven omnibus skills: `instrument-integration`, `instrument-product-analytics`, `instrument-error-tracking`, `instrument-llm-analytics`, `instrument-logs`, `instrument-metrics`, and `instrument-tracing`.
Baseline trigger coverage lives in [`products/feature_flags/evals/eval_instrument_flags.py`](../evals/eval_instrument_flags.py).
It grades the context-mill skill itself, so it needs that skill present in the sandbox and refuses to run without it — read its module docstring before running it.
diff --git a/products/posthog_ai/scripts/build_skills/reserved_names.py b/products/posthog_ai/scripts/build_skills/reserved_names.py
index 8c3ec219254c..223a5e50ac7f 100644
--- a/products/posthog_ai/scripts/build_skills/reserved_names.py
+++ b/products/posthog_ai/scripts/build_skills/reserved_names.py
@@ -15,6 +15,7 @@ OMNIBUS_SKILL_NAMES = frozenset(
"instrument-llm-analytics",
"instrument-logs",
"instrument-metrics",
+ "instrument-tracing",
}
)
diff --git a/products/skills/backend/bundled_skills.py b/products/skills/backend/bundled_skills.py
index d8a1bcb02560..72bd1597cdab 100644
--- a/products/skills/backend/bundled_skills.py
+++ b/products/skills/backend/bundled_skills.py
@@ -26,6 +26,8 @@ OMNIBUS_SKILL_NAMES = frozenset(
"instrument-error-tracking",
"instrument-llm-analytics",
"instrument-logs",
+ "instrument-metrics",
+ "instrument-tracing",
}
)
diff --git a/services/mcp/README.md b/services/mcp/README.md
index ec10f3b9b93f..10ffa05f1aed 100644
--- a/services/mcp/README.md
+++ b/services/mcp/README.md
@@ -314,6 +314,8 @@ The cached bytes are kept for thirty days and re-extended on every refresh, so a
No `learn`, `initialize`, or `discover` request reads the archive from Redis.
By default it is loaded from `https://github.com/PostHog/posthog/releases/download/agent-skills-latest/skills.zip`.
Set `POSTHOG_MCP_SKILLS_URL` to use another archive during local development.
+The context-mill omnibus skills are overlaid on that bundle from the shared copy the resource refresh publishes; set `POSTHOG_MCP_OMNIBUS_SKILLS=off` to serve the bundle alone.
+A pinned bundle (`POSTHOG_MCP_SKILLS_SHA256`) serves no overlay, and a product skill keeps its name when an overlay skill collides with it.
Custom archive URLs use separate Redis cache namespaces so a local bundle cannot read or overwrite the published bundle's cache entry.
Project skills are read directly from the request-authenticated project and are not cached by the MCP server.
Only latest, active, uncategorized skills are exposed through `learn`; category-specific skills such as scouts stay on their own surfaces.
diff --git a/services/mcp/src/hono/cache/ContextMillResourceCache.ts b/services/mcp/src/hono/cache/ContextMillResourceCache.ts
index 02dcfb5b1227..131f54fad1d6 100644
--- a/services/mcp/src/hono/cache/ContextMillResourceCache.ts
+++ b/services/mcp/src/hono/cache/ContextMillResourceCache.ts
@@ -1,9 +1,10 @@
import { createHash, randomUUID } from 'node:crypto'
-import { fetchAndExtractEntries } from '@/resources/internals'
+import { type ContextMillArchiveContents, fetchAndExtractEntries } from '@/resources/internals'
import type { ContextMillResource } from '@/resources/manifest-types'
import { contextMillBodyReadsTotal, contextMillCacheEventsTotal } from '../metrics'
+import type { OmnibusSkillsCache } from './OmnibusSkillsCache'
import type { RedisLike } from './RedisCache'
import { SharedBlobCache, type SharedBlobCacheOptions } from './SharedBlobCache'
@@ -31,6 +32,7 @@ export interface ResourceBody {
export interface ContextMillResourceCacheOptions extends SharedBlobCacheOptions {
bodyTtlSeconds?: number
localUrl?: string
+ omnibusSkills?: OmnibusSkillsCache
}
export type ContextMillCacheResult = 'fresh_hit' | 'stale_hit' | 'cold_refresh' | 'waited' | 'fallback'
@@ -65,10 +67,12 @@ export interface ContextMillLoadResult {
export class ContextMillResourceCache extends SharedBlobCache {
private readonly bodyTtlSeconds: number
private readonly localUrl: string | undefined
+ private readonly omnibusSkills: OmnibusSkillsCache | undefined
constructor(redis: RedisLike, opts: ContextMillResourceCacheOptions = {}) {
super(redis, `${NAMESPACE}:manifest`, opts)
this.localUrl = opts.localUrl
+ this.omnibusSkills = opts.omnibusSkills
this.bodyTtlSeconds = opts.bodyTtlSeconds ?? DEFAULT_BODY_TTL_SECONDS
}
@@ -131,8 +135,9 @@ export class ContextMillResourceCache extends SharedBlobCache {
}
private async loadBlob(): Promise<Uint8Array> {
- const entries = await this.loadEntries()
+ const { entries, omnibusSkillsArchive } = await this.loadArchiveContents()
await this.writeBodies(entries)
+ await this.publishOmnibusSkills(omnibusSkillsArchive)
const slim: SlimManifest = {
entries: entries.map((e) => ({
uri: e.uri,
@@ -144,8 +149,22 @@ export class ContextMillResourceCache extends SharedBlobCache {
return new TextEncoder().encode(JSON.stringify(slim))
}
- protected async loadEntries(): Promise<ContextMillResource[]> {
- return fetchAndExtractEntries(this.localUrl)
+ protected async loadArchiveContents(): Promise<ContextMillArchiveContents> {
+ return fetchAndExtractEntries(this.localUrl, this.omnibusSkills !== undefined)
+ }
+
+ /** A bad omnibus archive must not block the resource manifest, so it logs and keeps the last shared copy. */
+ private async publishOmnibusSkills(archive: Uint8Array | null): Promise<void> {
+ if (!this.omnibusSkills || !archive) {
+ return
+ }
+ try {
+ await this.omnibusSkills.publish(archive)
+ contextMillCacheEventsTotal.inc({ event: 'omnibus_published' })
+ } catch (err) {
+ contextMillCacheEventsTotal.inc({ event: 'omnibus_error' })
+ console.error('[ContextMillResourceCache] failed to publish the omnibus skills:', err)
+ }
}
private async refreshInBackground(): Promise<void> {
diff --git a/services/mcp/src/hono/cache/OmnibusSkillsCache.ts b/services/mcp/src/hono/cache/OmnibusSkillsCache.ts
new file mode 100644
index 000000000000..aec114d1f8be
--- /dev/null
+++ b/services/mcp/src/hono/cache/OmnibusSkillsCache.ts
@@ -0,0 +1,32 @@
+import { SkillCatalog } from '@/skills/skill-catalog'
+
+import type { RedisLike } from './RedisCache'
+import { hashBytes, SharedBlobCache, type SharedBlobCacheOptions } from './SharedBlobCache'
+
+const NAMESPACE = 'omnibus-skills'
+const DEFAULT_TTL_SECONDS = 30 * 24 * 60 * 60
+
+export class OmnibusSkillsCache extends SharedBlobCache {
+ constructor(redis: RedisLike, opts: SharedBlobCacheOptions = {}) {
+ super(redis, NAMESPACE, { cacheTtlSeconds: DEFAULT_TTL_SECONDS, ...opts })
+ }
+
+ /** Parses before publishing, so a release the catalog cannot load never becomes the shared copy. */
+ async publish(bytes: Uint8Array): Promise<void> {
+ SkillCatalog.fromZip(bytes)
+ const current = await this.readVersion()
+ if (current?.sha === hashBytes(bytes) && (await this.touchCache(current))) {
+ return
+ }
+ await this.writeCache(bytes)
+ }
+
+ async readIfChanged(currentSha: string | undefined): Promise<{ bytes: Uint8Array; sha: string } | null> {
+ const version = await this.readVersion()
+ if (!version || version.sha === currentSha) {
+ return null
+ }
+ const cached = await this.readCache(version)
+ return cached ? { bytes: cached.bytes, sha: cached.sha } : null
+ }
+}
diff --git a/services/mcp/src/hono/constants.ts b/services/mcp/src/hono/constants.ts
index 194fd1cda1d2..ca5c88bbedb5 100644
--- a/services/mcp/src/hono/constants.ts
+++ b/services/mcp/src/hono/constants.ts
@@ -41,6 +41,7 @@ export function getEnv(): Env {
POSTHOG_ANALYTICS_HOST: process.env.POSTHOG_ANALYTICS_HOST || undefined,
POSTHOG_MCP_SKILLS_URL: process.env.POSTHOG_MCP_SKILLS_URL || undefined,
POSTHOG_MCP_SKILLS_SHA256: process.env.POSTHOG_MCP_SKILLS_SHA256 || undefined,
+ POSTHOG_MCP_OMNIBUS_SKILLS: process.env.POSTHOG_MCP_OMNIBUS_SKILLS || undefined,
POSTHOG_MCP_LOCAL_SKILLS_URL: process.env.POSTHOG_MCP_LOCAL_SKILLS_URL || undefined,
...extras,
}
diff --git a/services/mcp/src/hono/dispatcher.ts b/services/mcp/src/hono/dispatcher.ts
index d5b3ee1b892e..9f40763b6ba0 100644
--- a/services/mcp/src/hono/dispatcher.ts
+++ b/services/mcp/src/hono/dispatcher.ts
@@ -40,6 +40,7 @@ import {
} from '@/lib/stateless-protocol'
import { trackInitEvent } from './analytics'
+import { OmnibusSkillsCache } from './cache/OmnibusSkillsCache'
import type { RedisLike } from './cache/RedisCache'
import { getEnv, MCP_EXEC_SKILLS_FEATURE_FLAG } from './constants'
import { GuidanceEngine } from './guidance/engine'
@@ -163,12 +164,14 @@ class McpDispatcher {
constructor(catalog: ToolCatalog, redis: RedisLike) {
const env = getEnv()
this.catalog = catalog
- this.resourceCatalog = new ResourceCatalog(env, redis)
+ const omnibusSkills = env.POSTHOG_MCP_OMNIBUS_SKILLS === 'off' ? undefined : new OmnibusSkillsCache(redis)
+ this.resourceCatalog = new ResourceCatalog(env, redis, omnibusSkills)
this.stateResolver = new RequestStateResolver(catalog, redis, env)
this.instructionsBuilder = new InstructionsBuilder(GUIDELINES)
this.skillCatalogService = new SkillCatalogService(redis, {
archiveUrl: env.POSTHOG_MCP_SKILLS_URL,
expectedArchiveSha: env.POSTHOG_MCP_SKILLS_SHA256,
+ omnibusSkills,
})
this.toolExecutor = new ToolExecutor(
catalog,
diff --git a/services/mcp/src/hono/resource-catalog.ts b/services/mcp/src/hono/resource-catalog.ts
index c1dc4b46c79d..9e608362a5af 100644
--- a/services/mcp/src/hono/resource-catalog.ts
+++ b/services/mcp/src/hono/resource-catalog.ts
@@ -19,6 +19,7 @@ import {
type ContextMillCacheResult,
type SlimManifestEntry,
} from './cache/ContextMillResourceCache'
+import type { OmnibusSkillsCache } from './cache/OmnibusSkillsCache'
import type { RedisLike } from './cache/RedisCache'
import {
contextMillManifestEntries,
@@ -40,10 +41,13 @@ export class ResourceCatalog {
private allResources: Resource[] = []
private contextMillEntriesByUri = new Map<string, SlimManifestEntry>()
- constructor(env: Env, redis: RedisLike) {
+ constructor(env: Env, redis: RedisLike, omnibusSkills?: OmnibusSkillsCache) {
this.env = env
const localUrl = this.contextMillLocalUrl()
- this.contextMillCache = new ContextMillResourceCache(redis, localUrl ? { localUrl } : {})
+ this.contextMillCache = new ContextMillResourceCache(redis, {
+ ...(localUrl ? { localUrl } : {}),
+ ...(omnibusSkills ? { omnibusSkills } : {}),
+ })
}
get contextMillEntries(): readonly SlimManifestEntry[] {
diff --git a/services/mcp/src/hono/skill-catalog-service.ts b/services/mcp/src/hono/skill-catalog-service.ts
index d2f05af3ca85..a1f3faf55ac6 100644
--- a/services/mcp/src/hono/skill-catalog-service.ts
+++ b/services/mcp/src/hono/skill-catalog-service.ts
@@ -1,5 +1,6 @@
import { SkillCatalog } from '@/skills/skill-catalog'
+import type { OmnibusSkillsCache } from './cache/OmnibusSkillsCache'
import type { RedisLike } from './cache/RedisCache'
import { hashBytes } from './cache/SharedBlobCache'
import { SkillArchiveCache, type SkillArchiveCacheOptions } from './cache/SkillArchiveCache'
@@ -24,6 +25,7 @@ export interface SkillCatalogServiceOptions extends SkillArchiveCacheOptions {
/** How long startup waits for a catalog before the pod serves without one. */
warmupTimeoutMs?: number
warmupRetryMs?: number
+ omnibusSkills?: OmnibusSkillsCache
}
type LoadPhase = 'warmup' | 'poll'
@@ -41,21 +43,33 @@ class SkillArchiveIntegrityError extends Error {}
export class SkillCatalogService {
private readonly expectedArchiveSha: string | undefined
private readonly archiveCache: SkillArchiveCache
+ private readonly omnibusSkills: OmnibusSkillsCache | undefined
private readonly pollIntervalMs: number
private readonly pollJitterMs: number
private readonly warmupTimeoutMs: number
private readonly warmupRetryMs: number
private catalog: SkillCatalog | undefined
+ private archiveBytes: Uint8Array | undefined
private archiveSha: string | undefined
+ private omnibusBytes: Uint8Array | undefined
+ private omnibusSha: string | undefined
private loadedAt: number | undefined
private timer: ReturnType<typeof setInterval> | undefined
private polling = false
constructor(redis: RedisLike, opts: SkillCatalogServiceOptions = {}) {
- const { expectedArchiveSha, pollIntervalMs, pollJitterMs, warmupTimeoutMs, warmupRetryMs, ...cacheOptions } =
- opts
+ const {
+ expectedArchiveSha,
+ pollIntervalMs,
+ pollJitterMs,
+ warmupTimeoutMs,
+ warmupRetryMs,
+ omnibusSkills,
+ ...cacheOptions
+ } = opts
this.expectedArchiveSha = expectedArchiveSha
+ this.omnibusSkills = omnibusSkills
const validateArchive =
cacheOptions.validateArchive ?? ((bytes: Uint8Array) => void SkillCatalog.fromZip(bytes))
this.archiveCache = new SkillArchiveCache(redis, {
@@ -90,6 +104,7 @@ export class SkillCatalogService {
const loaded = await this.archiveCache.loadOrRefresh()
skillArchiveEventsTotal.inc({ phase: 'warmup', result: loaded.result })
this.install(loaded.bytes, loaded.sha, 'warmup')
+ await this.adoptOmnibusSkills('warmup')
return
} catch (error) {
skillArchiveEventsTotal.inc({ phase: 'warmup', result: 'error' })
@@ -139,6 +154,7 @@ export class SkillCatalogService {
this.polling = true
try {
await this.adoptSharedArchive()
+ await this.adoptOmnibusSkills('poll')
const refresh = await this.archiveCache.refreshIfStale()
skillArchiveEventsTotal.inc({ phase: 'poll', result: refresh })
if (refresh === 'downloaded') {
@@ -175,20 +191,62 @@ export class SkillCatalogService {
}
}
+ private async adoptOmnibusSkills(phase: LoadPhase): Promise<void> {
+ // A pinned archive serves exactly its bytes, so no unpinned overlay joins it.
+ if (!this.omnibusSkills || !this.archiveBytes || this.expectedArchiveSha) {
+ return
+ }
+ try {
+ const changed = await this.omnibusSkills.readIfChanged(this.omnibusSha)
+ if (!changed) {
+ return
+ }
+ this.omnibusBytes = changed.bytes
+ this.omnibusSha = changed.sha
+ this.installCatalog(this.archiveBytes, phase)
+ skillArchiveEventsTotal.inc({ phase, result: 'omnibus_reloaded' })
+ } catch (error) {
+ skillArchiveEventsTotal.inc({ phase, result: 'omnibus_error' })
+ console.error('[SkillCatalogService] omnibus skills failed to load; keeping the current catalog:', error)
+ }
+ }
+
private install(bytes: Uint8Array, sha: string, phase: LoadPhase): void {
this.verifyArchive(bytes)
if (sha === this.archiveSha) {
return
}
+ this.archiveBytes = bytes
+ this.archiveSha = sha
+ this.installCatalog(bytes, phase)
+ }
+
+ private installCatalog(bytes: Uint8Array, phase: LoadPhase): void {
const start = Date.now()
- const catalog = SkillCatalog.fromZip(bytes)
+ const catalog = this.buildCatalog(bytes)
this.catalog = catalog
- this.archiveSha = sha
this.loadedAt = Date.now()
skillCatalogLoadDurationSeconds.observe({ phase }, (this.loadedAt - start) / 1000)
skillCatalogSkills.set(catalog.size)
skillCatalogAgeSeconds.set(0)
- console.info(`[SkillCatalogService] installed ${catalog.size} skills (${phase}, sha ${sha.slice(0, 12)})`)
+ console.info(
+ `[SkillCatalogService] installed ${catalog.size} skills (${phase}, sha ${this.archiveSha?.slice(0, 12)})`
+ )
+ }
+
+ /** The product archive must always install, so a failing overlay degrades to product skills only. */
+ private buildCatalog(bytes: Uint8Array): SkillCatalog {
+ if (this.omnibusBytes) {
+ try {
+ return SkillCatalog.fromZip(bytes, this.omnibusBytes)
+ } catch (error) {
+ console.error(
+ '[SkillCatalogService] omnibus skills failed to overlay; serving product skills only:',
+ error
+ )
+ }
+ }
+ return SkillCatalog.fromZip(bytes)
}
}
diff --git a/services/mcp/src/resources/internals.ts b/services/mcp/src/resources/internals.ts
index 7275df90688a..550f0d030e08 100644
--- a/services/mcp/src/resources/internals.ts
+++ b/services/mcp/src/resources/internals.ts
@@ -1,12 +1,29 @@
-import { type Unzipped, strFromU8, unzipSync } from 'fflate'
+import { type Unzipped, strFromU8, strToU8, unzipSync, zipSync } from 'fflate'
+
+import {
+ MAX_ARCHIVE_FILE_BYTES,
+ MAX_ARCHIVE_FILES,
+ MAX_ARCHIVE_UNCOMPRESSED_BYTES,
+ parseFrontmatter,
+} from '@/skills/skill-catalog'
import { loadContextMillManifest } from './manifest-loader'
import type { ContextMillManifest, ContextMillResource } from './manifest-types'
const CONTEXT_MILL_URL = 'https://github.com/PostHog/context-mill/releases/latest/download/skills-mcp-resources.zip'
+const OMNIBUS_ARCHIVE_PATTERN = /^omnibus-([a-z0-9]+(?:-[a-z0-9]+)*)\.zip$/
+// A fixed mtime keeps the repacked bytes, and so their sha, stable across refreshes of
+// an unchanged release; a wall-clock mtime would make every pod re-parse every refresh.
+const OMNIBUS_ARCHIVE_MTIME = new Date('2000-01-01T00:00:00Z')
+
let cachedResources: Unzipped | null = null
+export interface ContextMillArchiveContents {
+ entries: ContextMillResource[]
+ omnibusSkillsArchive: Uint8Array | null
+}
+
export type ArchiveLoader = (url: string) => Promise<Uint8Array>
async function defaultArchiveLoader(url: string, noStore: boolean): Promise<Uint8Array> {
@@ -65,16 +82,85 @@ export function filterValidEntries(entries: readonly ContextMillResource[], arch
})
}
+export function buildOmnibusSkillsArchive(archive: Unzipped): Uint8Array | null {
+ const files: Record<string, Uint8Array> = {}
+ let fileCount = 0
+ let totalUncompressedBytes = 0
+ for (const [entryName, entryBytes] of Object.entries(archive)) {
+ const match = OMNIBUS_ARCHIVE_PATTERN.exec(entryName)
+ if (!match) {
+ continue
+ }
+ const skillName = match[1]!
+ // The catalog applies the same limits to the repacked archive, but only after this
+ // inflate has already allocated; the filter stops a crafted release before that.
+ const inner = unzipSync(entryBytes, {
+ filter: (file) => {
+ if (file.name.endsWith('/')) {
+ return false
+ }
+ fileCount += 1
+ totalUncompressedBytes += file.originalSize
+ if (
+ fileCount > MAX_ARCHIVE_FILES ||
+ file.originalSize > MAX_ARCHIVE_FILE_BYTES ||
+ totalUncompressedBytes > MAX_ARCHIVE_UNCOMPRESSED_BYTES
+ ) {
+ throw new Error(`Omnibus archive "${entryName}" exceeds the extraction limit`)
+ }
+ return true
+ },
+ })
+ const skillFile = inner['SKILL.md']
+ const rewrittenSkillFile = skillFile ? strFromU8(skillFile).replace(/^(name:[ \t]*)omnibus-/m, '$1') : undefined
+ if (!rewrittenSkillFile || declaredSkillName(rewrittenSkillFile, entryName) !== skillName) {
+ // The served name comes from the filename, so a release cannot publish under another skill's name.
+ console.warn(`[context-mill] skipping "${entryName}": SKILL.md does not declare the name "${skillName}"`)
+ continue
+ }
+ for (const [path, bytes] of Object.entries(inner)) {
+ files[`${skillName}/${path}`] = path === 'SKILL.md' ? strToU8(rewrittenSkillFile) : bytes
+ }
+ }
+ // Level 1 keeps the writer pod's event loop short; the blob is read once per pod per release.
+ return Object.keys(files).length > 0 ? zipSync(files, { level: 1, mtime: OMNIBUS_ARCHIVE_MTIME }) : null
+}
+
+// Reads the name the way the catalog will, so a decoy `name:` line outside the frontmatter cannot pass.
+function declaredSkillName(skillFile: string, source: string): string | undefined {
+ try {
+ return parseFrontmatter(skillFile, source).name
+ } catch {
+ return undefined
+ }
+}
+
+// A bad omnibus zip must not cost the manifest, which the resource list depends on.
+function repackOmnibusSkills(archive: Unzipped): Uint8Array | null {
+ try {
+ return buildOmnibusSkillsArchive(archive)
+ } catch (error) {
+ console.error('[context-mill] omnibus skills could not be repacked; serving none:', error)
+ return null
+ }
+}
+
/**
- * Fetch + unzip + parse the context-mill manifest, returning the filtered
- * entries. Does not touch the module-level `cachedResources`; used by the
- * hono runtime to push entries into a Redis-sharded cache without retaining
- * the archive in process memory.
+ * Fetch + unzip + parse the context-mill archive, returning the filtered manifest
+ * entries and the repacked omnibus skills. Does not touch the module-level
+ * `cachedResources`; used by the hono runtime to push both into Redis-backed caches
+ * without retaining the archive in process memory.
*/
-export async function fetchAndExtractEntries(localUrl?: string): Promise<ContextMillResource[]> {
+export async function fetchAndExtractEntries(
+ localUrl?: string,
+ includeOmnibusSkills = true
+): Promise<ContextMillArchiveContents> {
const url = localUrl || CONTEXT_MILL_URL
const bytes = await defaultArchiveLoader(url, Boolean(localUrl))
const archive = unzipSync(bytes)
const manifest = loadManifestFromArchive(archive)
- return filterValidEntries(manifest.resources, archive)
+ return {
+ entries: filterValidEntries(manifest.resources, archive),
+ omnibusSkillsArchive: includeOmnibusSkills ? repackOmnibusSkills(archive) : null,
+ }
}
diff --git a/services/mcp/src/skills/skill-catalog.ts b/services/mcp/src/skills/skill-catalog.ts
index aaafe926c81e..5f6049701827 100644
--- a/services/mcp/src/skills/skill-catalog.ts
+++ b/services/mcp/src/skills/skill-catalog.ts
@@ -8,10 +8,14 @@ export const MAX_GLOBAL_SKILLS = 10
const MAX_GLOBAL_SNIPPETS = 2
const MAX_SCOPED_MATCHES = 50
const SEARCH_CONTEXT_LINES = 2
-const MAX_ARCHIVE_FILES = 5_000
-const MAX_ARCHIVE_FILE_BYTES = 8 * 1024 * 1024
-const MAX_ARCHIVE_UNCOMPRESSED_BYTES = 64 * 1024 * 1024
+export const MAX_ARCHIVE_FILES = 5_000
+export const MAX_ARCHIVE_FILE_BYTES = 8 * 1024 * 1024
+export const MAX_ARCHIVE_UNCOMPRESSED_BYTES = 64 * 1024 * 1024
const EXACT_NAME_SCORE_BONUS = 5_000
+// context-mill's omnibus skills ship docs snapshots and example apps as references, and
+// snippet matches in those would crowd the workflow skills out of the result limit. Search
+// scores them by name, description and SKILL.md only; reads by path stay open.
+const ENTRY_POINT_ONLY_SKILL_PREFIX = 'instrument-'
type SkillFileKind = 'markdown' | 'script' | 'other'
@@ -73,69 +77,19 @@ export class SkillCatalog {
}
}
- static fromZip(bytes: Uint8Array): SkillCatalog {
- let fileCount = 0
- let totalUncompressedBytes = 0
- const archive = unzipSync(bytes, {
- filter: (file) => {
- if (file.name.endsWith('/')) {
- return false
+ static fromZip(bytes: Uint8Array, overlayBytes?: Uint8Array): SkillCatalog {
+ const skillsByName = indexSkillsByName(parseSkillArchive(bytes))
+ if (overlayBytes) {
+ for (const [name, skill] of indexSkillsByName(parseSkillArchive(overlayBytes))) {
+ if (skillsByName.has(name)) {
+ // The product archive can be sha-pinned and the overlay is not, so the overlay never replaces a product skill.
+ console.warn(`[SkillCatalog] overlay skill "${name}" ignored: a product skill has that name`)
+ continue
}
- validateArchivePath(file.name)
- fileCount += 1
- totalUncompressedBytes += file.originalSize
- if (
- fileCount > MAX_ARCHIVE_FILES ||
- file.originalSize > MAX_ARCHIVE_FILE_BYTES ||
- totalUncompressedBytes > MAX_ARCHIVE_UNCOMPRESSED_BYTES
- ) {
- throw new Error('Skill archive exceeds the extraction limit')
- }
- return true
- },
- })
- const filesByDirectory = new Map<string, SkillFile[]>()
-
- for (const [archivePath, fileBytes] of Object.entries(archive)) {
- if (archivePath.endsWith('/')) {
- continue
- }
- const pathParts = validateArchivePath(archivePath)
- const directory = pathParts[0]!
- const relativePath = pathParts.slice(1).join('/')
- const content = normalizeText(strFromU8(fileBytes))
- if (content.includes('\0')) {
- throw new Error(`Skill archive contains a binary file: "${archivePath}"`)
- }
-
- const files = filesByDirectory.get(directory) ?? []
- if (files.some((file) => file.path === relativePath)) {
- throw new Error(`Duplicate skill file path: "${archivePath}"`)
- }
- files.push(makeSkillFile(relativePath, content))
- filesByDirectory.set(directory, files)
- }
-
- const skills = [...filesByDirectory.entries()].map(([directory, files]) => {
- const skillFile = files.find((file) => file.path === 'SKILL.md')
- if (!skillFile) {
- throw new Error(`Skill archive entry "${directory}" has no SKILL.md`)
- }
- const metadata = parseFrontmatter(skillFile.content, `${directory}/SKILL.md`)
- if (metadata.name === 'skills') {
- throw new Error('Skill name "skills" is reserved by the learn command')
- }
- return {
- name: metadata.name,
- description: metadata.description,
- files: files.sort((left, right) => compareSkillPaths(left.path, right.path)),
+ skillsByName.set(name, skill)
}
- })
-
- if (skills.length === 0) {
- throw new Error('Skill archive contains no skills')
}
- return new SkillCatalog(skills.sort((left, right) => left.name.localeCompare(right.name)))
+ return new SkillCatalog([...skillsByName.values()].sort((left, right) => left.name.localeCompare(right.name)))
}
get size(): number {
@@ -223,7 +177,7 @@ export class SkillCatalog {
const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---(?:\n|$)/
-function parseFrontmatter(content: string, source: string): { name: string; description: string } {
+export function parseFrontmatter(content: string, source: string): { name: string; description: string } {
const match = content.match(FRONTMATTER_PATTERN)
if (!match?.[1]) {
throw new Error(`Missing YAML frontmatter in "${source}"`)
@@ -424,6 +378,82 @@ export function formatLearnSearchResults(results: readonly LearnSearchResult[]):
return fitLearnOutput(sections.join('\n\n'))
}
+function indexSkillsByName(skills: readonly SkillDefinition[]): Map<string, SkillDefinition> {
+ const byName = new Map<string, SkillDefinition>()
+ for (const skill of skills) {
+ if (byName.has(skill.name)) {
+ throw new Error(`Duplicate skill name: "${skill.name}"`)
+ }
+ byName.set(skill.name, skill)
+ }
+ return byName
+}
+
+function parseSkillArchive(bytes: Uint8Array): SkillDefinition[] {
+ let fileCount = 0
+ let totalUncompressedBytes = 0
+ const archive = unzipSync(bytes, {
+ filter: (file) => {
+ if (file.name.endsWith('/')) {
+ return false
+ }
+ validateArchivePath(file.name)
+ fileCount += 1
+ totalUncompressedBytes += file.originalSize
+ if (
+ fileCount > MAX_ARCHIVE_FILES ||
+ file.originalSize > MAX_ARCHIVE_FILE_BYTES ||
+ totalUncompressedBytes > MAX_ARCHIVE_UNCOMPRESSED_BYTES
+ ) {
+ throw new Error('Skill archive exceeds the extraction limit')
+ }
+ return true
+ },
+ })
+ const filesByDirectory = new Map<string, SkillFile[]>()
+
+ for (const [archivePath, fileBytes] of Object.entries(archive)) {
+ if (archivePath.endsWith('/')) {
+ continue
+ }
+ const pathParts = validateArchivePath(archivePath)
+ const directory = pathParts[0]!
+ const relativePath = pathParts.slice(1).join('/')
+ const content = normalizeText(strFromU8(fileBytes))
+ if (content.includes('\0')) {
+ throw new Error(`Skill archive contains a binary file: "${archivePath}"`)
+ }
+
+ const files = filesByDirectory.get(directory) ?? []
+ if (files.some((file) => file.path === relativePath)) {
+ throw new Error(`Duplicate skill file path: "${archivePath}"`)
+ }
+ files.push(makeSkillFile(relativePath, content))
+ filesByDirectory.set(directory, files)
+ }
+
+ const skills = [...filesByDirectory.entries()].map(([directory, files]) => {
+ const skillFile = files.find((file) => file.path === 'SKILL.md')
+ if (!skillFile) {
+ throw new Error(`Skill archive entry "${directory}" has no SKILL.md`)
+ }
+ const metadata = parseFrontmatter(skillFile.content, `${directory}/SKILL.md`)
+ if (metadata.name === 'skills') {
+ throw new Error('Skill name "skills" is reserved by the learn command')
+ }
+ return {
+ name: metadata.name,
+ description: metadata.description,
+ files: files.sort((left, right) => compareSkillPaths(left.path, right.path)),
+ }
+ })
+
+ if (skills.length === 0) {
+ throw new Error('Skill archive contains no skills')
+ }
+ return skills
+}
+
function rankSkill(skill: SkillDefinition, query: NormalizedQuery): RankedSkill | null {
let score =
(skill.name.toLowerCase() === query.phrase ? EXACT_NAME_SCORE_BONUS : 0) +
@@ -435,6 +465,9 @@ function rankSkill(skill: SkillDefinition, query: NormalizedQuery): RankedSkill
for (const file of skill.files) {
const isSkillFile = file.path === 'SKILL.md'
+ if (!isSkillFile && skill.name.startsWith(ENTRY_POINT_ONLY_SKILL_PREFIX)) {
+ continue
+ }
if (!isSkillFile) {
filePathScore = Math.max(filePathScore, scoreText(file.path, query, 120))
}
diff --git a/services/mcp/src/tools/types.ts b/services/mcp/src/tools/types.ts
index 1c9ffddd13e0..9b5cbf4802ca 100644
--- a/services/mcp/src/tools/types.ts
+++ b/services/mcp/src/tools/types.ts
@@ -127,6 +127,8 @@ export type Env = {
/** Override the published product skills archive, primarily for local development. */
POSTHOG_MCP_SKILLS_URL?: string | undefined
POSTHOG_MCP_SKILLS_SHA256?: string | undefined
+ /** `off` serves the product skills archive without the context-mill omnibus overlay. */
+ POSTHOG_MCP_OMNIBUS_SKILLS?: string | undefined
POSTHOG_MCP_LOCAL_SKILLS_URL?: string | undefined
}
diff --git a/services/mcp/tests/hono/context-mill-resource-cache.test.ts b/services/mcp/tests/hono/context-mill-resource-cache.test.ts
index 0ad71a9f03a7..40d06f8fb2fd 100644
--- a/services/mcp/tests/hono/context-mill-resource-cache.test.ts
+++ b/services/mcp/tests/hono/context-mill-resource-cache.test.ts
@@ -1,3 +1,4 @@
+import { strToU8, zipSync } from 'fflate'
import { createHash } from 'node:crypto'
import { beforeEach, describe, expect, it, vi } from 'vitest'
@@ -12,13 +13,16 @@ vi.mock('@/hono/metrics', () => ({
}))
import { ContextMillResourceCache, type ContextMillResourceCacheOptions } from '@/hono/cache/ContextMillResourceCache'
+import { OmnibusSkillsCache } from '@/hono/cache/OmnibusSkillsCache'
import type { RedisLike } from '@/hono/cache/RedisCache'
+import type { ContextMillArchiveContents } from '@/resources/internals'
import type { ContextMillResource } from '@/resources/manifest-types'
+import { SkillCatalog } from '@/skills/skill-catalog'
import { makeRedisRateLimitStubs } from './helpers/redis-rate-limit-stubs'
import { makeSharedBlobRedisStubs } from './helpers/shared-blob-redis-stubs'
-type EntryLoader = () => Promise<ContextMillResource[]>
+type EntryLoader = () => Promise<ContextMillResource[] | ContextMillArchiveContents>
class TestContextMillResourceCache extends ContextMillResourceCache {
constructor(
@@ -33,8 +37,9 @@ class TestContextMillResourceCache extends ContextMillResourceCache {
this.loader = loader
}
- protected override loadEntries(): Promise<ContextMillResource[]> {
- return this.loader()
+ protected override async loadArchiveContents(): Promise<ContextMillArchiveContents> {
+ const loaded = await this.loader()
+ return Array.isArray(loaded) ? { entries: loaded, omnibusSkillsArchive: null } : loaded
}
}
@@ -130,6 +135,40 @@ describe('ContextMillResourceCache', () => {
expect(mockCacheEventsInc).toHaveBeenCalledWith({ event: 'lock_acquired' })
})
+ it('publishes the omnibus skills with the manifest and keeps the last copy when a release does not parse', async () => {
+ const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+ try {
+ const omnibus = new OmnibusSkillsCache(redis)
+ const skillArchive = (name: string): Uint8Array =>
+ zipSync({
+ [`${name}/SKILL.md`]: strToU8(`---\nname: ${name}\ndescription: Add ${name}.\n---\n\n# ${name}`),
+ })
+ const cache = new TestContextMillResourceCache(
+ redis,
+ async () => ({ entries: [makeEntry('a')], omnibusSkillsArchive: skillArchive('instrument-logs') }),
+ { omnibusSkills: omnibus }
+ )
+
+ await cache.loadOrRefresh()
+ const published = await omnibus.readIfChanged(undefined)
+ expect(SkillCatalog.fromZip(published!.bytes).listNames()).toEqual(['instrument-logs'])
+ expect(mockCacheEventsInc).toHaveBeenCalledWith({ event: 'omnibus_published' })
+
+ await cache.invalidate()
+ cache.setLoader(async () => ({
+ entries: [makeEntry('b')],
+ omnibusSkillsArchive: zipSync({ 'broken/notes.md': strToU8('no entry point') }),
+ }))
+ const { manifest } = await cache.loadOrRefresh()
+
+ expect(manifest.entries.map((entry) => entry.uri)).toEqual(['posthog://skill/b'])
+ expect(await omnibus.readIfChanged(published!.sha)).toBeNull()
+ expect(mockCacheEventsInc).toHaveBeenCalledWith({ event: 'omnibus_error' })
+ } finally {
+ consoleError.mockRestore()
+ }
+ })
+
it('serves manifest from cache on warm hit without calling upstream', async () => {
const entries = [makeEntry('a')]
const cache = new TestContextMillResourceCache(redis, async () => entries)
diff --git a/services/mcp/tests/hono/integration-harness.test.ts b/services/mcp/tests/hono/integration-harness.test.ts
index 0bbb87bfc426..edd350d3153d 100644
--- a/services/mcp/tests/hono/integration-harness.test.ts
+++ b/services/mcp/tests/hono/integration-harness.test.ts
@@ -52,7 +52,7 @@ describe('Hono integration harness', () => {
expect(error?.code).toBe('EADDRINUSE')
const contextMillUrl = getEnv().POSTHOG_MCP_LOCAL_SKILLS_URL
expect(contextMillUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+\//)
- const entries = await fetchAndExtractEntries(contextMillUrl)
+ const { entries } = await fetchAndExtractEntries(contextMillUrl)
expect(entries.some((entry) => entry.uri.startsWith('posthog://'))).toBe(true)
if (fails) {
throw new Error('warmup failed')
diff --git a/services/mcp/tests/hono/resource-catalog.test.ts b/services/mcp/tests/hono/resource-catalog.test.ts
index 3245be604722..146a03eaf4a1 100644
--- a/services/mcp/tests/hono/resource-catalog.test.ts
+++ b/services/mcp/tests/hono/resource-catalog.test.ts
@@ -110,7 +110,10 @@ describe('ResourceCatalog', () => {
describe('warmup and resource listing', () => {
it('serves slim metadata for context-mill resources after warmup', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([makeEntry('guide'), makeEntry('faq')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({
+ entries: [makeEntry('guide'), makeEntry('faq')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockResolvedValue([
{
name: 'greet',
@@ -144,7 +147,10 @@ describe('ResourceCatalog', () => {
})
it('pre-merges resource list so getResourcesList returns a stable array', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([makeEntry('a')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({
+ entries: [makeEntry('a')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -156,7 +162,7 @@ describe('ResourceCatalog', () => {
})
it('lists the Visual Review artifact source in its CSP metadata', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({ entries: [], omnibusSkillsArchive: null })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -173,14 +179,20 @@ describe('ResourceCatalog', () => {
})
it('revalidates context-mill resources on demand', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValueOnce([makeEntry('old')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValueOnce({
+ entries: [makeEntry('old')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
await catalog.warmup()
redis._store.delete(MANIFEST_CURRENT_KEY)
- vi.mocked(fetchAndExtractEntries).mockResolvedValueOnce([makeEntry('new')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValueOnce({
+ entries: [makeEntry('new')],
+ omnibusSkillsArchive: null,
+ })
await catalog.revalidateContextMillResources('initialize')
@@ -197,7 +209,10 @@ describe('ResourceCatalog', () => {
it('keeps existing context-mill resources when revalidation fails', async () => {
const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
try {
- vi.mocked(fetchAndExtractEntries).mockResolvedValueOnce([makeEntry('stable')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValueOnce({
+ entries: [makeEntry('stable')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -227,7 +242,7 @@ describe('ResourceCatalog', () => {
describe('readResource', () => {
it('includes the Visual Review artifact source in its CSP metadata', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({ entries: [], omnibusSkillsArchive: null })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -242,7 +257,10 @@ describe('ResourceCatalog', () => {
})
it('lazy-loads a context-mill body from Redis on first read', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([makeEntry('doc')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({
+ entries: [makeEntry('doc')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -256,7 +274,7 @@ describe('ResourceCatalog', () => {
})
it('returns empty contents for unknown URI', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({ entries: [], omnibusSkillsArchive: null })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -267,7 +285,10 @@ describe('ResourceCatalog', () => {
})
it('returns empty contents when a body has aged out without triggering a refresh', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([makeEntry('doc')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({
+ entries: [makeEntry('doc')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -295,7 +316,7 @@ describe('ResourceCatalog', () => {
describe('getPrompt', () => {
it('returns messages for a known prompt name', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({ entries: [], omnibusSkillsArchive: null })
vi.mocked(getPromptsFromManifest).mockResolvedValue([
{
name: 'test-prompt',
@@ -313,7 +334,7 @@ describe('ResourceCatalog', () => {
})
it('returns empty messages for unknown prompt', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({ entries: [], omnibusSkillsArchive: null })
vi.mocked(getPromptsFromManifest).mockResolvedValue([])
const catalog = new ResourceCatalog(mockEnv, redis)
@@ -340,7 +361,10 @@ describe('ResourceCatalog', () => {
})
it('continues serving resources when prompt fetch fails', async () => {
- vi.mocked(fetchAndExtractEntries).mockResolvedValue([makeEntry('r')])
+ vi.mocked(fetchAndExtractEntries).mockResolvedValue({
+ entries: [makeEntry('r')],
+ omnibusSkillsArchive: null,
+ })
vi.mocked(getPromptsFromManifest).mockRejectedValue(new Error('fail'))
const catalog = new ResourceCatalog(mockEnv, redis)
diff --git a/services/mcp/tests/unit/context-mill-archive.test.ts b/services/mcp/tests/unit/context-mill-archive.test.ts
index 869f3893c079..7b5d0b90fa4f 100644
--- a/services/mcp/tests/unit/context-mill-archive.test.ts
+++ b/services/mcp/tests/unit/context-mill-archive.test.ts
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
import { fetchAndExtractEntries } from '@/resources/internals'
import type { ContextMillResource } from '@/resources/manifest-types'
+import { SkillCatalog } from '@/skills/skill-catalog'
const ARCHIVE_URL = 'http://127.0.0.1/skills-mcp-resources.zip'
@@ -30,7 +31,7 @@ describe('fetchAndExtractEntries', () => {
vi.restoreAllMocks()
})
- it('serves the manifest entries whose backing file is in the archive', async () => {
+ it('serves the manifest entries whose backing file is in the archive and repacks the omnibus skills', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
const manifest = {
version: '1.0',
@@ -43,11 +44,41 @@ describe('fetchAndExtractEntries', () => {
stubArchiveResponse({
'manifest.json': strToU8(JSON.stringify(manifest)),
'skills/bundled.md': strToU8('# bundled'),
+ 'omnibus-instrument-logs.zip': zipSync({
+ 'SKILL.md': strToU8('---\nname: omnibus-instrument-logs\ndescription: Add logs.\n---\n\n# Add logs'),
+ 'references/go.md': strToU8('# Go'),
+ }),
+ 'omnibus-querying-posthog-data.zip': zipSync({
+ 'SKILL.md': strToU8(
+ '---\n"name": omnibus-other\ndescription: Wrong name.\n---\n\nname: omnibus-querying-posthog-data\n'
+ ),
+ }),
})
- const entries = await fetchAndExtractEntries(ARCHIVE_URL)
+ const { entries, omnibusSkillsArchive } = await fetchAndExtractEntries(ARCHIVE_URL)
expect(entries.map((entry) => entry.id)).toEqual(['bundled', 'inline'])
+ const omnibus = SkillCatalog.fromZip(omnibusSkillsArchive!)
+ expect(omnibus.listNames()).toEqual(['instrument-logs'])
+ expect(omnibus.read('instrument-logs', 'references/go.md')).toContain('# Go')
+ expect((await fetchAndExtractEntries(ARCHIVE_URL, false)).omnibusSkillsArchive).toBeNull()
+ })
+
+ it.each([
+ ['corrupt', strToU8('not a zip')],
+ ['oversized', zipSync({ 'SKILL.md': new Uint8Array(9 * 1024 * 1024) })],
+ ])('serves the entries with no overlay when an omnibus zip is %s', async (_label, inner) => {
+ const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+ stubArchiveResponse({
+ 'manifest.json': strToU8(JSON.stringify({ version: '1.0', resources: [manifestEntry('inline')] })),
+ 'omnibus-instrument-logs.zip': inner,
+ })
+
+ const { entries, omnibusSkillsArchive } = await fetchAndExtractEntries(ARCHIVE_URL)
+
+ expect(entries.map((entry) => entry.id)).toEqual(['inline'])
+ expect(omnibusSkillsArchive).toBeNull()
+ expect(consoleError).toHaveBeenCalledTimes(1)
})
it('rejects an archive without a manifest', async () => {
diff --git a/services/mcp/tests/unit/skill-archive-cache.test.ts b/services/mcp/tests/unit/skill-archive-cache.test.ts
index 0fa17c740fed..99cfaf4aba01 100644
--- a/services/mcp/tests/unit/skill-archive-cache.test.ts
+++ b/services/mcp/tests/unit/skill-archive-cache.test.ts
@@ -1,6 +1,7 @@
import { strToU8, zipSync } from 'fflate'
import { describe, expect, it, vi } from 'vitest'
+import { OmnibusSkillsCache } from '@/hono/cache/OmnibusSkillsCache'
import type { RedisLike } from '@/hono/cache/RedisCache'
import { hashBytes } from '@/hono/cache/SharedBlobCache'
import { SkillArchiveCache, type SkillArchiveFetchResult } from '@/hono/cache/SkillArchiveCache'
@@ -357,6 +358,37 @@ describe('SkillCatalogService', () => {
}
})
+ it('overlays the shared omnibus skills, follows their updates, and refuses a copy that does not parse', async () => {
+ const redis = makeRedis()
+ const omnibus = new OmnibusSkillsCache(redis)
+ await omnibus.publish(makeArchive('instrument-logs'))
+ const service = new SkillCatalogService(redis, {
+ fetchArchive: async () => downloaded(makeArchive('product')),
+ omnibusSkills: omnibus,
+ })
+
+ await service.warmup()
+ expect(service.getCatalog()?.listNames()).toEqual(['instrument-logs', 'product'])
+
+ await omnibus.publish(makeArchive('instrument-tracing'))
+ await service.poll()
+ expect(service.getCatalog()?.listNames()).toEqual(['instrument-tracing', 'product'])
+
+ await expect(omnibus.publish(zipSync({ 'broken/notes.md': strToU8('no entry point') }))).rejects.toThrow(
+ 'has no SKILL.md'
+ )
+ await service.poll()
+ expect(service.getCatalog()?.listNames()).toEqual(['instrument-tracing', 'product'])
+
+ const pinned = new SkillCatalogService(redis, {
+ fetchArchive: async () => downloaded(makeArchive('product')),
+ expectedArchiveSha: hashBytes(makeArchive('product')),
+ omnibusSkills: omnibus,
+ })
+ await pinned.warmup()
+ expect(pinned.getCatalog()?.listNames()).toEqual(['product'])
+ })
+
it('loads a new pin at the same URL without reusing an older cached archive', async () => {
const redis = makeRedis()
const firstBytes = makeArchive('first')
diff --git a/services/mcp/tests/unit/skill-catalog.test.ts b/services/mcp/tests/unit/skill-catalog.test.ts
index 50276a0f8cb3..54f0f7652b92 100644
--- a/services/mcp/tests/unit/skill-catalog.test.ts
+++ b/services/mcp/tests/unit/skill-catalog.test.ts
@@ -105,6 +105,58 @@ describe('SkillCatalog and exec learn', () => {
})
})
+ it('overlays a second archive, keeps the product skill on a shared name, and rejects duplicates within one archive', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ try {
+ const catalog = SkillCatalog.fromZip(
+ makeArchive({
+ 'funnels/SKILL.md': makeSkill('funnels', 'Product funnels.', '# Funnels'),
+ 'retention-analysis/SKILL.md': makeSkill('retention-analysis', 'Retention.', '# Retention'),
+ }),
+ makeArchive({
+ 'funnels/SKILL.md': makeSkill('funnels', 'Overlay funnels.', '# Overlay funnels'),
+ 'instrument-logs/SKILL.md': makeSkill('instrument-logs', 'Add logs.', '# Add logs'),
+ })
+ )
+
+ expect(catalog.listNames()).toEqual(['funnels', 'instrument-logs', 'retention-analysis'])
+ expect(catalog.describe('funnels')).toBe('Product funnels.')
+ expect(warn).toHaveBeenCalledTimes(1)
+ expect(() =>
+ SkillCatalog.fromZip(
+ makeArchive({
+ 'a/SKILL.md': makeSkill('twice', 'One.', '# One'),
+ 'b/SKILL.md': makeSkill('twice', 'Two.', '# Two'),
+ })
+ )
+ ).toThrow('Duplicate skill name')
+ } finally {
+ warn.mockRestore()
+ }
+ })
+
+ it('scores an omnibus instrument skill by its entry point only, never its references', () => {
+ const catalog = SkillCatalog.fromZip(
+ makeArchive({
+ 'instrument-logs/SKILL.md': makeSkill(
+ 'instrument-logs',
+ 'Add PostHog log capture to an app.',
+ '# Add logs\n\nInstall the SDK and ship logs.'
+ ),
+ 'instrument-logs/references/go.md': '# Go\n\nConfigure the zerolog adapter.',
+ 'investigating-logs/SKILL.md': makeSkill(
+ 'investigating-logs',
+ 'Find failing requests in logs.',
+ '# Investigating logs\n\nFilter zerolog output by severity.'
+ ),
+ })
+ )
+
+ expect(catalog.searchResults('zerolog').map((result) => result.identifier)).toEqual(['investigating-logs'])
+ expect(catalog.searchResults('capture').map((result) => result.identifier)).toEqual(['instrument-logs'])
+ expect(catalog.read('instrument-logs', 'references/go.md')).toContain('zerolog adapter')
+ })
+
it('ranks an exact name before substring matches at the result limit', () => {
const names = [
...Array.from({ length: MAX_GLOBAL_SKILLS }, (_, index) => `${String.fromCharCode(97 + index)}-support`),