@coldiq/mcp 0.3.14 → 0.3.16

package/src/skills.ts

@@ -0,0 +1,108 @@
+// ColdIQ GTM skills, served over MCP.
+//
+// Skills are step-by-step playbooks authored in the coldiq-marketplace-skills
+// repo. Claude Code and Cursor load them natively (progressive disclosure), but
+// agents without a skills loader (Codex, Windsurf, Cline, …) can't. Since every
+// agent that installs this MCP gets these two tools, the MCP is the universal
+// delivery channel: list_skills surfaces the catalog, load_skill fetches one
+// playbook on demand.
+//
+// Source is the repo's discovery index on GitHub raw, so a push to the skills
+// repo updates what every agent sees — no MCP republish needed. Override with
+// COLDIQ_SKILLS_INDEX_URL.
+
+const DEFAULT_INDEX_URL =
+  'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json'
+const INDEX_TTL_MS = 10 * 60 * 1000 // re-fetch the catalog at most every 10 min
+
+export interface SkillEntry {
+  name: string
+  description: string
+  url: string
+  digest?: string
+}
+
+interface CachedIndex {
+  skills: SkillEntry[]
+  fetchedAt: number
+}
+
+let _indexCache: CachedIndex | null = null
+const _bodyCache = new Map<string, string>()
+
+/** Test seam: clear in-memory caches. */
+export function __resetSkillsCache(): void {
+  _indexCache = null
+  _bodyCache.clear()
+}
+
+function indexUrl(): string {
+  return process.env.COLDIQ_SKILLS_INDEX_URL || DEFAULT_INDEX_URL
+}
+
+async function fetchText(url: string): Promise<string> {
+  const res = await fetch(url, { headers: { 'user-agent': 'coldiq-mcp' } })
+  if (!res.ok) throw new Error(`request to ${url} failed (HTTP ${res.status})`)
+  return await res.text()
+}
+
+async function getIndex(): Promise<SkillEntry[]> {
+  if (_indexCache && Date.now() - _indexCache.fetchedAt < INDEX_TTL_MS) {
+    return _indexCache.skills
+  }
+  const parsed = JSON.parse(await fetchText(indexUrl()))
+  const raw = Array.isArray(parsed?.skills) ? parsed.skills : []
+  const skills: SkillEntry[] = raw
+    .filter((s: unknown): s is Record<string, unknown> => !!s && typeof s === 'object')
+    .map((s: Record<string, unknown>) => ({
+      name: String(s.name ?? ''),
+      description: String(s.description ?? ''),
+      url: String(s.url ?? ''),
+      digest: typeof s.digest === 'string' ? s.digest : undefined,
+    }))
+    .filter((s: SkillEntry) => s.name && s.url)
+  _indexCache = { skills, fetchedAt: Date.now() }
+  return skills
+}
+
+/** The catalog: each skill's name + one-line description (no bodies). */
+export async function listSkills(): Promise<{ name: string; description: string }[]> {
+  const skills = await getIndex()
+  return skills.map((s) => ({ name: s.name, description: s.description }))
+}
+
+/**
+ * Full playbook body for `name`. Any `resources/<file>.md` the skill references
+ * is fetched and appended so the returned document is self-contained (agents
+ * reached over MCP can't follow the relative links themselves).
+ */
+export async function loadSkill(name: string): Promise<string> {
+  const skills = await getIndex()
+  const entry = skills.find((s) => s.name === name)
+  if (!entry) {
+    throw new Error(`unknown skill "${name}". Available: ${skills.map((s) => s.name).join(', ')}`)
+  }
+  if (_bodyCache.has(entry.url)) return _bodyCache.get(entry.url) as string
+
+  const body = await fetchText(entry.url)
+  const refs = new Set<string>()
+  for (const m of body.matchAll(/resources\/([A-Za-z0-9._-]+\.md)/g)) refs.add(m[1])
+
+  let combined = body
+  if (refs.size > 0) {
+    const baseDir = entry.url.replace(/\/[^/]*$/, '') // strip trailing SKILL.md
+    const sections: string[] = []
+    for (const ref of refs) {
+      try {
+        const text = await fetchText(`${baseDir}/resources/${ref}`)
+        sections.push(`\n\n---\n\n## Resource: resources/${ref}\n\n${text.trim()}`)
+      } catch {
+        // A missing resource shouldn't fail the whole skill load.
+      }
+    }
+    combined = body.replace(/\s+$/, '') + sections.join('') + '\n'
+  }
+
+  _bodyCache.set(entry.url, combined)
+  return combined
+}

package/src/tools/list-skills.ts

@@ -0,0 +1,25 @@
+import { listSkills } from '../skills.js'
+
+export const listSkillsName = 'list_skills'
+
+export const listSkillsDescription =
+  'List the available ColdIQ GTM playbooks ("skills") — step-by-step expert workflows for go-to-market ' +
+  'tasks: building a TAM, Apollo / company / people search, contact enrichment and email waterfalls, ' +
+  'signal detection, ICP & personas, cold-email copy, campaign delivery, and more. Returns each skill\'s ' +
+  'name and a one-line description of when to use it. Call this when starting a prospecting / outreach / ' +
+  'GTM task to check for a relevant playbook, then call load_skill to read the full step-by-step guide. ' +
+  '(Claude Code and Cursor load these skills natively; on other agents this is how you reach them.)'
+
+export const listSkillsSchema = {}
+
+export async function listSkillsHandler(_input: Record<string, unknown>) {
+  try {
+    const skills = await listSkills()
+    return { content: [{ type: 'text' as const, text: JSON.stringify({ data: skills }) }] }
+  } catch (err) {
+    return {
+      content: [{ type: 'text' as const, text: JSON.stringify({ error: `Could not load the ColdIQ skills catalog: ${(err as Error).message}` }) }],
+      isError: true,
+    }
+  }
+}

package/src/tools/load-skill.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import { loadSkill } from '../skills.js'
+
+export const loadSkillName = 'load_skill'
+
+export const loadSkillDescription =
+  'Load the full ColdIQ GTM playbook ("skill") by name — the complete step-by-step expert workflow, ' +
+  'including which ColdIQ tools/endpoints to call at each step. Call list_skills first to get the available ' +
+  'names. The returned guide (with any referenced reference docs inlined) tells you exactly how to run the ' +
+  'task using the other ColdIQ tools.'
+
+export const loadSkillSchema = {
+  name: z
+    .string()
+    .describe('The skill name from list_skills, e.g. "contact-enrichment", "apollo-search", or "tam-scoring".'),
+}
+
+export async function loadSkillHandler(input: Record<string, unknown>) {
+  const name = String(input.name ?? '').trim()
+  if (!name) {
+    return {
+      content: [{ type: 'text' as const, text: 'Provide a skill "name" — call list_skills to see the available skills.' }],
+      isError: true,
+    }
+  }
+  try {
+    const body = await loadSkill(name)
+    return { content: [{ type: 'text' as const, text: body }] }
+  } catch (err) {
+    return { content: [{ type: 'text' as const, text: (err as Error).message }], isError: true }
+  }
+}

package/src/tools/search-ads.ts

@@ -5,17 +5,17 @@ import { getProvidersForCapability } from '../utils/provider-resolver.js'
 export const searchAdsName = 'search_ads'
 
 export const searchAdsDescription =
-  'Search live ad creatives across 5 ad libraries (Google Ads Transparency, LinkedIn Ad Library, Meta Ads Library, Twitter/X Ads, Reddit Ads) — a high-signal GTM input for competitive intelligence, ICP refinement, and pitch personalization. Routes by input: domains/advertiser_ids → Google only; search_urls → LinkedIn only; bare query → Google → Meta → Twitter → Reddit waterfall. Use platform="google"|"linkedin"|"meta"|"twitter"|"reddit" to pin to one platform. All providers are async (~10–60s). Cost: ~5 credits per call (Twitter charges 1 credit per ad returned). Credits are fully refunded when a run returns zero ads. NOTE: Google Ads creatives return image URLs + creative IDs, not ad copy text — open the image URLs to read the ad. There is no "currently running only" filter; results can span past campaigns.'
+  'Search live ad creatives across 4 ad libraries (Google Ads Transparency, LinkedIn Ad Library, Meta Ads Library, Twitter/X Ads) — a high-signal GTM input for competitive intelligence, ICP refinement, and pitch personalization. Routes by input: domains/advertiser_ids → Google only; search_urls → LinkedIn only; bare query → Google → Meta → Twitter waterfall. Use platform="google"|"linkedin"|"meta"|"twitter" to pin to one platform. All providers are async (~10–60s). Cost: ~5 credits per call (Twitter charges 1 credit per ad returned). Credits are fully refunded when a run returns zero ads. NOTE: Google Ads creatives return image URLs + creative IDs, not ad copy text — open the image URLs to read the ad. There is no "currently running only" filter; results can span past campaigns.'
 
 export const searchAdsSchema = {
-  query: z.string().optional().describe('Advertiser/company name or keyword. Routes to Google→Meta→Twitter→Reddit when no platform-specific input is set.'),
+  query: z.string().optional().describe('Advertiser/company name or keyword. Routes to Google→Meta→Twitter when no platform-specific input is set.'),
 
   domains: z.array(z.string()).optional().describe('Company domains (e.g. ["salesforce.com"]). Routes to Google Ads only.'),
   advertiser_ids: z.array(z.string()).optional().describe('Google Ads Transparency advertiser IDs (e.g. ["AR16735076323512287233"]). Routes to Google Ads only.'),
 
   search_urls: z.array(z.string()).optional().describe('Pre-built LinkedIn Ad Library URLs from linkedin.com/ad-library. Routes to LinkedIn only. Build at linkedin.com/ad-library/search using accountOwner/countries/dateOption filters.'),
 
-  country: z.string().optional().describe('ISO country code (2-letter for Meta/Twitter; longer accepted by Google as region). Ignored by Reddit.'),
+  country: z.string().optional().describe('ISO country code (2-letter for Meta/Twitter; longer accepted by Google as region).'),
   max_results: z.number().int().min(1).max(200).default(25).describe('Max ads per provider call (1–200). Per-provider caps: Google 1000, LinkedIn 200, Meta 200, Twitter 100. Twitter charges 1 credit per ad returned.'),
 
   ad_type: z.enum(['ALL', 'POLITICAL_AND_ISSUE_ADS']).optional().describe('Meta only. Defaults to ALL.'),
@@ -23,17 +23,7 @@ export const searchAdsSchema = {
   start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Twitter only. Date range start, YYYY-MM-DD.'),
   end_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Twitter only. Date range end, YYYY-MM-DD.'),
 
-  industry: z.enum([
-    'TECH_B2C', 'TECH_B2B', 'EDUCATION', 'ENTERTAINMENT', 'HEALTH_AND_BEAUTY',
-    'GAMING', 'EMPLOYMENT', 'RETAIL_AND_ECOMMERCE', 'AUTO', 'FINANCIAL_SERVICES',
-    'TRAVEL', 'REAL_ESTATE', 'GAMBLING_AND_FANTASY_SPORTS', 'POLITICS_AND_GOVERNMENT',
-    'CONSUMER_PACKAGED_GOODS', 'OTHER',
-  ]).optional().describe('Reddit only. Filter by industry category.'),
-  budget_category: z.enum(['LOW', 'MEDIUM', 'HIGH']).optional().describe('Reddit only.'),
-  post_type: z.enum(['IMAGE', 'VIDEO', 'TEXT']).optional().describe('Reddit only.'),
-  objective_type: z.enum(['AWARENESS', 'CONVERSIONS', 'APP_INSTALLS', 'TRAFFIC', 'VIDEO_VIEWABLE_IMPRESSIONS']).optional().describe('Reddit only.'),
-
-  platform: z.enum(['google', 'linkedin', 'meta', 'twitter', 'reddit']).optional().describe('Pin to one platform; skips all others. Useful for cross-platform comparison via separate calls.'),
+  platform: z.enum(['google', 'linkedin', 'meta', 'twitter']).optional().describe('Pin to one platform; skips all others. Useful for cross-platform comparison via separate calls.'),
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_ads').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 

package/src/utils/provider-display.ts

@@ -3,7 +3,7 @@
 // ---------------------------------------------------------------------------
 //
 // Internal provider IDs (registry.ts + the find_emails waterfall) are a mix of
-// clean vendor names ("apollo"), already-branded slugs ("reddit_ads"), and ugly
+// clean vendor names ("apollo"), already-branded slugs ("linkedin_ad_library"), and ugly
 // internal slugs ("limadata-work-email"). User-facing surfaces — the selection
 // insight and `_meta.provider_name` — must show a clean branded label instead.
 //
@@ -11,7 +11,7 @@
 // the ColdIQ "we picked the best tool" intelligence on display. The ONLY thing
 // that must never surface is the Apify backend — and since no ID contains the
 // word "Apify", that constraint is satisfied by mapping the Apify-backed scrapers
-// to their branded data-source name (e.g. "Reddit Ads").
+// to their branded data-source name (e.g. "LinkedIn Ad Library").
 // ---------------------------------------------------------------------------
 
 const DISPLAY_NAMES: Record<string, string> = {
@@ -96,7 +96,6 @@ const DISPLAY_NAMES: Record<string, string> = {
   linkedin_ad_library: 'LinkedIn Ad Library',
   meta_ads: 'Meta Ads',
   twitter_ads: 'X Ads',
-  reddit_ads: 'Reddit Ads',
 
   // --- search_places / reviews ---------------------------------------------
   google_maps: 'Google Maps',

package/src/utils/provider-resolver.ts

@@ -268,7 +268,6 @@ const GATED_DESCRIPTIONS: Partial<Record<Capability, Partial<Record<string, Gate
     linkedin_ad_library: { kind: 'requires',          fields: 'search_urls (pre-built LinkedIn Ad Library URLs)' },
     meta_ads:            { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
     twitter_ads:         { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
-    reddit_ads:          { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
   },
   // -------------------------------------------------------------------------
   search_places: {

package/src/utils/selection-insight.ts

@@ -148,7 +148,6 @@ const STRENGTHS: Partial<Record<InsightCapability, Record<string, string>>> = {
     linkedin_ad_library: 'LinkedIn Ad Library coverage',
     meta_ads: 'Meta (Facebook/Instagram) ad-library coverage',
     twitter_ads: 'X ad coverage',
-    reddit_ads: 'Reddit ad coverage',
   },
   search_places: {
     openmart: 'rich local-business data across the US, CA, AU, PR and NZ',

package/tests/registry.test.ts

@@ -1493,9 +1493,9 @@ describe('registry', () => {
   })
 
   describe('search_ads', () => {
-    it('providers are ordered google_ads → linkedin_ad_library → meta_ads → twitter_ads → reddit_ads', () => {
+    it('providers are ordered google_ads → linkedin_ad_library → meta_ads → twitter_ads', () => {
       const ids = getProviders('search_ads').map((p) => p.id)
-      expect(ids).toEqual(['google_ads', 'linkedin_ad_library', 'meta_ads', 'twitter_ads', 'reddit_ads'])
+      expect(ids).toEqual(['google_ads', 'linkedin_ad_library', 'meta_ads', 'twitter_ads'])
     })
 
     it('google_ads is async POST to /google-ads/search', () => {
@@ -1537,17 +1537,6 @@ describe('registry', () => {
       expect(t.async!.pollEndpoint('8')).toBe('/twitter-ads-scraper/search/8')
     })
 
-    it('reddit_ads is async POST to /reddit-ads/scrape', () => {
-      const r = getProviders('search_ads').find((p) => p.id === 'reddit_ads')!
-      expect(r.method).toBe('POST')
-      expect(r.endpoint).toBe('/reddit-ads/scrape')
-      expect(r.async!.pollEndpoint('5')).toBe('/reddit-ads/scrape/5')
-      expect(r.async!.isComplete({ status: 'done' })).toBe(true)
-      expect(r.async!.isComplete({ status: 'failed' })).toBe(true)
-      expect(r.async!.isComplete({ status: 'timed_out' })).toBe(true)
-      expect(r.async!.isComplete({ status: 'processing' })).toBe(false)
-    })
-
     it('google_ads.isApplicable: true for query/domains/advertiser_ids, false for empty or wrong platform', () => {
       const g = getProviders('search_ads').find((p) => p.id === 'google_ads')!
       expect(g.isApplicable!({ query: 'Salesforce' })).toBe(true)
@@ -1591,18 +1580,6 @@ describe('registry', () => {
       expect(t.isApplicable!({ query: 'ColdIQ', platform: 'twitter' })).toBe(true)
     })
 
-    it('reddit_ads.isApplicable: true for empty/query, false when domains/advertiser_ids/search_urls set', () => {
-      const r = getProviders('search_ads').find((p) => p.id === 'reddit_ads')!
-      expect(r.isApplicable!({})).toBe(true)
-      expect(r.isApplicable!({ query: 'sales automation' })).toBe(true)
-      expect(r.isApplicable!({ industry: 'TECH_B2B' })).toBe(true)
-      expect(r.isApplicable!({ domains: ['coldiq.com'] })).toBe(false)
-      expect(r.isApplicable!({ advertiser_ids: ['AR123'] })).toBe(false)
-      expect(r.isApplicable!({ search_urls: ['https://...'] })).toBe(false)
-      expect(r.isApplicable!({ platform: 'google' })).toBe(false)
-      expect(r.isApplicable!({ platform: 'reddit' })).toBe(true)
-    })
-
     it('platform pin: platform=linkedin makes only linkedin_ad_library applicable (even without search_urls it fails the URL check)', () => {
       const providers = getProviders('search_ads')
       const pinned = { platform: 'linkedin', query: 'Salesforce' }
@@ -1667,30 +1644,7 @@ describe('registry', () => {
       expect(capped.maxItems).toBe(100)
     })
 
-    it('reddit_ads.mapParams: query→keywords, forwards industry/budget_category/post_type/objective_type', () => {
-      const r = getProviders('search_ads').find((p) => p.id === 'reddit_ads')!
-      const out = r.mapParams({
-        query: 'sales automation',
-        industry: 'TECH_B2B',
-        budget_category: 'HIGH',
-        post_type: 'VIDEO',
-        objective_type: 'CONVERSIONS',
-      }).body as Record<string, unknown>
-      expect(out.keywords).toBe('sales automation')
-      expect(out.industry).toBe('TECH_B2B')
-      expect(out.budgetCategory).toBe('HIGH')
-      expect(out.postType).toBe('VIDEO')
-      expect(out.objectiveType).toBe('CONVERSIONS')
-    })
-
-    it('reddit_ads.mapParams: query is optional (scrape-all)', () => {
-      const r = getProviders('search_ads').find((p) => p.id === 'reddit_ads')!
-      const out = r.mapParams({ industry: 'TECH_B2B' }).body as Record<string, unknown>
-      expect(out.keywords).toBeUndefined()
-      expect(out.industry).toBe('TECH_B2B')
-    })
-
-    it('hasResult requires ads[] non-empty for all 5 providers', () => {
+    it('hasResult requires ads[] non-empty for all 4 providers', () => {
       const providers = getProviders('search_ads')
       for (const p of providers) {
         expect(p.hasResult({ ads: [{ id: '1' }] }), `${p.id} should return true`).toBe(true)

package/tests/skills.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { listSkills, loadSkill, __resetSkillsCache } from '../src/skills.js'
+
+const INDEX = {
+  $schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+  name: 'coldiq',
+  skills: [
+    {
+      name: 'contact-enrichment',
+      type: 'skill-md',
+      description: 'Enrich contacts with emails and phones.',
+      url: 'https://raw.example/skills/contact-enrichment/SKILL.md',
+      digest: 'sha256:abc',
+    },
+    {
+      name: 'coldiq-search-enrich',
+      type: 'skill-md',
+      description: 'Search and enrich at scale.',
+      url: 'https://raw.example/skills/lima-data-api/SKILL.md',
+    },
+  ],
+}
+
+const BODY_WITH_RES =
+  '# Contact enrichment\n\nSee [resources/async-job-pattern.md](resources/async-job-pattern.md) and ' +
+  '[resources/credit-optimization.md](resources/credit-optimization.md).\n'
+
+function mockFetch(map: Record<string, { status?: number; body: string }>) {
+  return vi.fn(async (url: string | URL | Request) => {
+    const u = String(url)
+    const hit = map[u]
+    if (!hit) return { ok: false, status: 404, text: async () => 'not found' } as Response
+    const status = hit.status ?? 200
+    return { ok: status >= 200 && status < 300, status, text: async () => hit.body } as Response
+  })
+}
+
+const originalFetch = globalThis.fetch
+
+describe('skills module', () => {
+  beforeEach(() => {
+    __resetSkillsCache()
+    delete process.env.COLDIQ_SKILLS_INDEX_URL
+  })
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  it('listSkills returns name + description from the index', async () => {
+    globalThis.fetch = mockFetch({
+      'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json': {
+        body: JSON.stringify(INDEX),
+      },
+    }) as typeof fetch
+    const skills = await listSkills()
+    expect(skills).toHaveLength(2)
+    expect(skills[0]).toEqual({ name: 'contact-enrichment', description: 'Enrich contacts with emails and phones.' })
+    expect(skills.map((s) => s.name)).toContain('coldiq-search-enrich')
+  })
+
+  it('honors COLDIQ_SKILLS_INDEX_URL override', async () => {
+    process.env.COLDIQ_SKILLS_INDEX_URL = 'https://custom/index.json'
+    globalThis.fetch = mockFetch({ 'https://custom/index.json': { body: JSON.stringify(INDEX) } }) as typeof fetch
+    const skills = await listSkills()
+    expect(skills).toHaveLength(2)
+  })
+
+  it('caches the index (one network call across two listSkills)', async () => {
+    const f = mockFetch({
+      'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json': {
+        body: JSON.stringify(INDEX),
+      },
+    })
+    globalThis.fetch = f as typeof fetch
+    await listSkills()
+    await listSkills()
+    expect(f).toHaveBeenCalledTimes(1)
+  })
+
+  it('loadSkill returns the body with referenced resources inlined', async () => {
+    globalThis.fetch = mockFetch({
+      'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json': {
+        body: JSON.stringify(INDEX),
+      },
+      'https://raw.example/skills/contact-enrichment/SKILL.md': { body: BODY_WITH_RES },
+      'https://raw.example/skills/contact-enrichment/resources/async-job-pattern.md': { body: 'POLL LOOP DOC' },
+      'https://raw.example/skills/contact-enrichment/resources/credit-optimization.md': { body: 'CREDIT DOC' },
+    }) as typeof fetch
+    const doc = await loadSkill('contact-enrichment')
+    expect(doc).toContain('# Contact enrichment')
+    expect(doc).toContain('## Resource: resources/async-job-pattern.md')
+    expect(doc).toContain('POLL LOOP DOC')
+    expect(doc).toContain('## Resource: resources/credit-optimization.md')
+    expect(doc).toContain('CREDIT DOC')
+  })
+
+  it('loadSkill tolerates a missing resource (skips it, still returns body)', async () => {
+    globalThis.fetch = mockFetch({
+      'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json': {
+        body: JSON.stringify(INDEX),
+      },
+      'https://raw.example/skills/contact-enrichment/SKILL.md': { body: BODY_WITH_RES },
+      // resources intentionally 404
+    }) as typeof fetch
+    const doc = await loadSkill('contact-enrichment')
+    expect(doc).toContain('# Contact enrichment')
+    expect(doc).not.toContain('POLL LOOP DOC')
+  })
+
+  it('loadSkill resolves folder≠name via the index url', async () => {
+    globalThis.fetch = mockFetch({
+      'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json': {
+        body: JSON.stringify(INDEX),
+      },
+      'https://raw.example/skills/lima-data-api/SKILL.md': { body: '# Search & enrich\n' },
+    }) as typeof fetch
+    const doc = await loadSkill('coldiq-search-enrich')
+    expect(doc).toContain('# Search & enrich')
+  })
+
+  it('loadSkill throws a helpful error for an unknown skill', async () => {
+    globalThis.fetch = mockFetch({
+      'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json': {
+        body: JSON.stringify(INDEX),
+      },
+    }) as typeof fetch
+    await expect(loadSkill('does-not-exist')).rejects.toThrow(/unknown skill/i)
+  })
+})

package/tests/tools/list-skills.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import {
+  listSkillsHandler,
+  listSkillsName,
+  listSkillsSchema,
+} from '../../src/tools/list-skills.js'
+import { __resetSkillsCache } from '../../src/skills.js'
+
+const INDEX_URL =
+  'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json'
+const originalFetch = globalThis.fetch
+
+describe('list_skills handler', () => {
+  beforeEach(() => __resetSkillsCache())
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  it('is a zero-arg tool', () => {
+    expect(listSkillsName).toBe('list_skills')
+    expect(listSkillsSchema).toEqual({})
+  })
+
+  it('returns the catalog as { data: [...] }', async () => {
+    globalThis.fetch = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () =>
+        JSON.stringify({ skills: [{ name: 'tam-scoring', description: 'Score a TAM.', url: 'https://x/SKILL.md' }] }),
+    })) as unknown as typeof fetch
+    const res = await listSkillsHandler({})
+    expect(res.isError).toBeFalsy()
+    const parsed = JSON.parse(res.content[0].text)
+    expect(parsed.data).toEqual([{ name: 'tam-scoring', description: 'Score a TAM.' }])
+  })
+
+  it('returns an error result (not a throw) when the index is unreachable', async () => {
+    globalThis.fetch = vi.fn(async () => ({ ok: false, status: 500, text: async () => 'err' })) as unknown as typeof fetch
+    const res = await listSkillsHandler({})
+    expect(res.isError).toBe(true)
+    expect(JSON.parse(res.content[0].text).error).toMatch(/could not load/i)
+  })
+})

package/tests/tools/load-skill.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { loadSkillHandler, loadSkillName, loadSkillSchema } from '../../src/tools/load-skill.js'
+import { __resetSkillsCache } from '../../src/skills.js'
+
+const INDEX_URL =
+  'https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/.well-known/agent-skills/index.json'
+
+function mockFetch(map: Record<string, string>) {
+  return vi.fn(async (url: string | URL | Request) => {
+    const body = map[String(url)]
+    return { ok: body !== undefined, status: body !== undefined ? 200 : 404, text: async () => body ?? 'nf' } as Response
+  })
+}
+const originalFetch = globalThis.fetch
+
+describe('load_skill handler', () => {
+  beforeEach(() => __resetSkillsCache())
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  it('declares a required name arg', () => {
+    expect(loadSkillName).toBe('load_skill')
+    expect(Object.keys(loadSkillSchema)).toContain('name')
+  })
+
+  it('returns the skill body as text', async () => {
+    globalThis.fetch = mockFetch({
+      [INDEX_URL]: JSON.stringify({ skills: [{ name: 'apollo-search', description: 'd', url: 'https://x/skills/apollo-search/SKILL.md' }] }),
+      'https://x/skills/apollo-search/SKILL.md': '# Apollo search\nstep 1',
+    }) as typeof fetch
+    const res = await loadSkillHandler({ name: 'apollo-search' })
+    expect(res.isError).toBeFalsy()
+    expect(res.content[0].text).toContain('# Apollo search')
+  })
+
+  it('errors (not throws) on a missing name', async () => {
+    const res = await loadSkillHandler({})
+    expect(res.isError).toBe(true)
+    expect(res.content[0].text).toMatch(/list_skills/)
+  })
+
+  it('errors with the available list on an unknown skill', async () => {
+    globalThis.fetch = mockFetch({
+      [INDEX_URL]: JSON.stringify({ skills: [{ name: 'apollo-search', description: 'd', url: 'https://x/SKILL.md' }] }),
+    }) as typeof fetch
+    const res = await loadSkillHandler({ name: 'nope' })
+    expect(res.isError).toBe(true)
+    expect(res.content[0].text).toMatch(/unknown skill/i)
+    expect(res.content[0].text).toMatch(/apollo-search/)
+  })
+})

package/tests/utils/provider-display.test.ts

@@ -16,7 +16,7 @@ describe('providerDisplayName', () => {
   })
 
   it('brands Apify-backed scrapers as their data source, never raw slug', () => {
-    expect(providerDisplayName('reddit_ads')).toBe('Reddit Ads')
+    expect(providerDisplayName('meta_ads')).toBe('Meta Ads')
     expect(providerDisplayName('linkedin_ad_library')).toBe('LinkedIn Ad Library')
     expect(providerDisplayName('google_maps')).toBe('Google Maps')
   })
@@ -28,7 +28,7 @@ describe('providerDisplayName', () => {
 
   it('never returns a raw slug or the word "Apify"', () => {
     const ids = [
-      'limadata-work-email', 'reddit_ads', 'fullenrich', 'ai-ark-people',
+      'limadata-work-email', 'twitter_ads', 'fullenrich', 'ai-ark-people',
       'linkupapi-validate', 'theirstack-buying-intents', 'completely_unknown_slug',
     ]
     for (const id of ids) {