: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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.mdindex 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" skillsfrom 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` overwrittenwhile 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.mdindex 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.pyindex 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.pyindex 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.mdindex 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 aNo `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.tsindex 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?: numberlocalUrl?: 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: numberprivate readonly localUrl: string | undefined+ private readonly omnibusSkills: OmnibusSkillsCache | undefinedconstructor(redis: RedisLike, opts: ContextMillResourceCacheOptions = {}) {super(redis, `${NAMESPACE}:manifest`, opts)this.localUrl = opts.localUrl+ this.omnibusSkills = opts.omnibusSkillsthis.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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 = envconst 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.tsindex 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?: numberwarmupRetryMs?: number+ omnibusSkills?: OmnibusSkillsCache}type LoadPhase = 'warmup' | 'poll'@@ -41,21 +43,33 @@ class SkillArchiveIntegrityError extends Error {}export class SkillCatalogService {private readonly expectedArchiveSha: string | undefinedprivate readonly archiveCache: SkillArchiveCache+ private readonly omnibusSkills: OmnibusSkillsCache | undefinedprivate readonly pollIntervalMs: numberprivate readonly pollJitterMs: numberprivate readonly warmupTimeoutMs: numberprivate readonly warmupRetryMs: numberprivate catalog: SkillCatalog | undefined+ private archiveBytes: Uint8Array | undefinedprivate archiveSha: string | undefined+ private omnibusBytes: Uint8Array | undefined+ private omnibusSha: string | undefinedprivate loadedAt: number | undefinedprivate timer: ReturnType<typeof setInterval> | undefinedprivate polling = falseconstructor(redis: RedisLike, opts: SkillCatalogServiceOptions = {}) {- const { expectedArchiveSha, pollIntervalMs, pollJitterMs, warmupTimeoutMs, warmupRetryMs, ...cacheOptions } =- opts+ const {+ expectedArchiveSha,+ pollIntervalMs,+ pollJitterMs,+ warmupTimeoutMs,+ warmupRetryMs,+ omnibusSkills,+ ...cacheOptions+ } = optsthis.expectedArchiveSha = expectedArchiveSha+ this.omnibusSkills = omnibusSkillsconst 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 = truetry {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 = shathis.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.tsindex 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_URLconst 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.tsindex 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 = 10const MAX_GLOBAL_SNIPPETS = 2const MAX_SCOPED_MATCHES = 50const 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 * 1024const 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): RankedSkillfor (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.tsindex 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 | undefinedPOSTHOG_MCP_SKILLS_SHA256?: string | undefined+ /** `off` serves the product skills archive without the context-mill omnibus overlay. */+ POSTHOG_MCP_OMNIBUS_SKILLS?: string | undefinedPOSTHOG_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.tsindex 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.tsindex 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_URLexpect(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.tsindex 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.tsindex 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.tsindex 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.tsindex 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`),