diff --git a/.changeset/skill-search-bm25.md b/.changeset/skill-search-bm25.md
new file mode 100644
index 000000000..70820061d
--- /dev/null
+++ b/.changeset/skill-search-bm25.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Add BM25-based skill search for large catalogues. When >80 skills are installed, the system prompt switches from a full listing to a compact name-only format and the model discovers skills via the Skill tool's new `action: "search"` endpoint. Startup memory reduced ~95% via lazy content loading.
diff --git a/packages/agent-core/src/agent/skill/types.ts b/packages/agent-core/src/agent/skill/types.ts
index 19413b8a2..b2ad15228 100644
--- a/packages/agent-core/src/agent/skill/types.ts
+++ b/packages/agent-core/src/agent/skill/types.ts
@@ -1,4 +1,5 @@
 import type { SkillDefinition } from '../../skill';
+import type { SkillSearchResult } from '../../skill/search';
 
 export interface SkillRegistry {
   getSkill(name: string): SkillDefinition | undefined;
@@ -7,4 +8,5 @@ export interface SkillRegistry {
   listInvocableSkills(): readonly SkillDefinition[];
   getSkillRoots(): readonly string[];
   getModelSkillListing(): string;
+  searchSkills(query: string, limit?: number): readonly SkillSearchResult[];
 }
diff --git a/packages/agent-core/src/profile/default/system.md b/packages/agent-core/src/profile/default/system.md
index d3b0084cc..ebcc5d0bc 100644
--- a/packages/agent-core/src/profile/default/system.md
+++ b/packages/agent-core/src/profile/default/system.md
@@ -132,9 +132,12 @@ Skills are modular extensions that provide:
 
 ## How to use skills
 
-Identify the skills that are likely to be useful for the tasks you are currently working on, read the skill file for detailed instructions, guidelines, scripts and more.
+When you need a skill, follow this two-step process:
 
-Only read skill details when needed to conserve the context window.
+1. **Search**: Call the `Skill` tool with `action: "search"` and relevant keywords to find matching skills. The search returns ranked results instantly.
+2. **Load**: Once you identify the right skill from search results, call the `Skill` tool with `action: "load"` and the skill name to load its full instructions into context.
+
+Only read skill details when needed to conserve the context window. Do NOT guess skill names — always search first when the skill listing above does not contain enough detail.
 
 ## Available skills
 
diff --git a/packages/agent-core/src/skill/index.ts b/packages/agent-core/src/skill/index.ts
index 924027bfa..cc98b9e2c 100644
--- a/packages/agent-core/src/skill/index.ts
+++ b/packages/agent-core/src/skill/index.ts
@@ -2,4 +2,5 @@ export * from './builtin';
 export * from './parser';
 export * from './registry';
 export * from './scanner';
+export * from './search';
 export * from './types';
diff --git a/packages/agent-core/src/skill/parser.ts b/packages/agent-core/src/skill/parser.ts
index 23d281c9d..48a851d85 100644
--- a/packages/agent-core/src/skill/parser.ts
+++ b/packages/agent-core/src/skill/parser.ts
@@ -1,3 +1,4 @@
+import { createReadStream } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'pathe';
 
@@ -8,6 +9,13 @@ import type { SkillDefinition, SkillMetadata, SkillSource } from './types';
 import { isSupportedSkillType } from './types';
 import { escapeXmlTags } from '../utils/xml-escape';
 
+/**
+ * Sentinel stored in SkillDefinition.content when only frontmatter was
+ * parsed at startup.  renderSkillPrompt() checks for this to decide
+ * whether to lazy-load the full body from disk.
+ */
+export const LAZY_CONTENT_SENTINEL = '\u0000LAZY';
+
 export class FrontmatterError extends Error {
   constructor(message: string, cause?: unknown) {
     super(message);
@@ -79,6 +87,75 @@ export async function parseSkillFromFile(options: ParseSkillOptions): Promise<Sk
   return parseSkillText({ ...options, text });
 }
 
+/**
+ * Read only the frontmatter from a SKILL.md file, leaving `content` empty.
+ * The body is not read from disk — callers can load it later via
+ * `readFile` + `parseSkillText` when the full content is actually needed.
+ *
+ * This avoids loading the full body of thousands of SKILL files into memory
+ * at startup when only the index (name, description) is needed.
+ */
+export async function parseSkillMetaFromFile(options: ParseSkillOptions): Promise<SkillDefinition> {
+  const stream = createReadStream(options.skillMdPath, { encoding: 'utf8', highWaterMark: 4096 });
+  let buffer = '';
+  let fenceCount = 0;
+
+  try {
+    for await (const chunk of stream) {
+      buffer += chunk;
+      const fences = buffer.match(/^---\s*$/gm);
+      if (fences !== null && fences.length >= 2) {
+        fenceCount = 2;
+        break;
+      }
+    }
+  } finally {
+    stream.close();
+  }
+
+  if (fenceCount < 2) {
+    return parseSkillFromFile(options);
+  }
+
+  // Find the exact end of the second fence in the original buffer so the
+  // slice works for both LF and CRLF line endings. `split('\n')` keeps a
+  // trailing '\r' on CRLF lines, so the fence line itself is '---\r' (length
+  // 4) and must be included in full; hard-coding +3 only works for LF.
+  let fencesFound = 0;
+  let offset = 0;
+  let fenceLineLength = 0;
+  const lines = buffer.split('\n');
+  for (const line of lines) {
+    const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line;
+    if (/^---\s*$/.test(trimmed)) {
+      fencesFound++;
+      if (fencesFound === 2) {
+        fenceLineLength = line.length;
+        break;
+      }
+    }
+    offset += line.length + 1; // +1 for the \n that split removed
+  }
+
+  const frontmatterOnly = buffer.slice(0, offset + fenceLineLength);
+  const bodyStart = offset + fenceLineLength;
+  const bodySnippet = buffer.slice(bodyStart, bodyStart + 1024).trim() || undefined;
+
+  const result = parseSkillText({ ...options, text: frontmatterOnly });
+  const definition = { ...result, content: LAZY_CONTENT_SENTINEL, bodySnippet };
+
+  // Flat .md skills are allowed to omit description and derive it from the
+  // first body line. The frontmatter-only parse has no body, so re-parse the
+  // full file when that fallback was triggered.
+  const isDirectorySkill = path.basename(options.skillMdPath) === 'SKILL.md';
+  if (!isDirectorySkill && definition.description === 'No description provided.') {
+    const full = await parseSkillFromFile(options);
+    return { ...definition, description: full.description };
+  }
+
+  return definition;
+}
+
 export function parseFrontmatter(text: string): ParsedFrontmatter {
   const lines = text.split(/\r?\n/);
   if (lines[0]?.trim() !== FENCE) {
@@ -242,12 +319,13 @@ function normalizeMetadata(raw: Record<string, unknown>): SkillMetadata {
 }
 
 function descriptionFromBody(body: string): string {
-  const firstLine = body
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .find((line) => line.length > 0);
-  if (firstLine === undefined) return 'No description provided.';
-  return firstLine.length > 240 ? `${firstLine.slice(0, 239)}…` : firstLine;
+  const lines = body.split(/\r?\n/).map((line) => line.trim());
+  const firstSentence = lines
+    .join(' ')
+    .match(/[^.!?]+[.!?]+/);
+  const candidate = firstSentence?.[0]?.trim() ?? lines.find((line) => line.length > 0);
+  if (candidate === undefined) return 'No description provided.';
+  return candidate.length > 240 ? `${candidate.slice(0, 239)}…` : candidate;
 }
 
 function tokenizeArgs(raw: string): string[] {
diff --git a/packages/agent-core/src/skill/registry.ts b/packages/agent-core/src/skill/registry.ts
index c3052491a..87932be60 100644
--- a/packages/agent-core/src/skill/registry.ts
+++ b/packages/agent-core/src/skill/registry.ts
@@ -1,5 +1,8 @@
-import { expandSkillParameters, skillArgumentNames } from './parser';
+import { readFileSync } from 'node:fs';
+
+import { LAZY_CONTENT_SENTINEL, expandSkillParameters, skillArgumentNames, parseSkillMetaFromFile, parseSkillText } from './parser';
 import { discoverSkills, type DiscoverSkillsOptions } from './scanner';
+import { SkillSearchIndex, type SkillSearchResult } from './search';
 import type { SkillDefinition, SkillRoot, SkillSource, SkippedSkill } from './types';
 import { isInlineSkillType, normalizeSkillName } from './types';
 import type { SkillRegistry as AgentSkillRegistry } from '../agent/skill/types';
@@ -7,6 +10,20 @@ import { escapeXmlAttr } from '../utils/xml-escape';
 
 const LISTING_DESC_MAX = 250;
 
+/**
+ * Above this threshold, getModelSkillListing() switches to a compact
+ * name-only listing and tells the model to use the `skill_search` tool.
+ * Below it, the legacy full listing is injected into the system prompt
+ * (cheaper for prompt caching with small catalogues).
+ */
+const COMPACT_LISTING_THRESHOLD = 80;
+
+/**
+ * Above this threshold, the compact listing drops descriptions entirely
+ * and lists only skill names.
+ */
+const NAMES_ONLY_LISTING_THRESHOLD = 300;
+
 export class SkillNotFoundError extends Error {
   readonly skillName: string;
 
@@ -21,6 +38,8 @@ export interface SkillRegistryOptions {
   readonly discover?: typeof discoverSkills;
   readonly onWarning?: (message: string, cause?: unknown) => void;
   readonly sessionId?: string;
+  readonly compactListingThreshold?: number;
+  readonly namesOnlyListingThreshold?: number;
 }
 
 export class SessionSkillRegistry implements AgentSkillRegistry {
@@ -31,20 +50,34 @@ export class SessionSkillRegistry implements AgentSkillRegistry {
   private readonly discoverImpl: typeof discoverSkills;
   private readonly onWarning: (message: string, cause?: unknown) => void;
   readonly sessionId?: string;
+  private readonly searchIndex = new SkillSearchIndex();
+  private readonly compactListingThreshold: number;
+  private readonly namesOnlyListingThreshold: number;
+
+  private indexDirty = false;
+  private modelSkillListingCache: string | undefined;
 
   constructor(options: SkillRegistryOptions = {}) {
     this.discoverImpl = options.discover ?? discoverSkills;
     this.onWarning = options.onWarning ?? (() => {});
     this.sessionId = options.sessionId;
+    this.compactListingThreshold = options.compactListingThreshold ?? COMPACT_LISTING_THRESHOLD;
+    this.namesOnlyListingThreshold = options.namesOnlyListingThreshold ?? NAMES_ONLY_LISTING_THRESHOLD;
   }
 
   async loadRoots(roots: readonly SkillRoot[]): Promise<void> {
+    this.modelSkillListingCache = undefined;
     for (const root of roots) {
       if (!this.roots.includes(root.path)) this.roots.push(root.path);
     }
 
+    // Only parse frontmatter at startup (name, description, whenToUse).
+    // The full body is loaded on demand when renderSkillPrompt() is called.
+    // This saves ~95% memory for large skill catalogues.
+
     const skills = await this.discoverImpl({
       roots,
+      parse: parseSkillMetaFromFile,
       onWarning: this.onWarning,
       onSkippedByPolicy: (skill) => this.skipped.push(skill),
       onDiscoveredSkill: (skill) => {
@@ -55,6 +88,12 @@ export class SessionSkillRegistry implements AgentSkillRegistry {
     for (const skill of skills) {
       this.byName.set(normalizeSkillName(skill.name), skill);
     }
+
+    // Build the BM25 search index so the model can discover skills
+    // via the `skill_search` tool instead of scanning a full listing.
+    // Sub-skills are excluded: they are intentionally hidden from the model
+    // and reachable only through their parent skill.
+    this.searchIndex.build(this.listSearchableSkills());
   }
 
   registerBuiltinSkill(skill: SkillDefinition): void {
@@ -65,6 +104,8 @@ export class SessionSkillRegistry implements AgentSkillRegistry {
     const key = normalizeSkillName(skill.name);
     if (options.replace === true || !this.byName.has(key)) {
       this.byName.set(key, skill);
+      this.indexDirty = true;
+      this.modelSkillListingCache = undefined;
     }
     this.indexPluginSkill(skill, options);
   }
@@ -89,8 +130,22 @@ export class SessionSkillRegistry implements AgentSkillRegistry {
   }
 
   renderSkillPrompt(skill: SkillDefinition, rawArgs: string): string {
+    // Lazy content loading: when compact mode parsed only frontmatter,
+    // the body is empty. Read the full file now (sync, only for activated skills).
+    let content = skill.content;
+    if (content === LAZY_CONTENT_SENTINEL && skill.path.length > 0) {
+      const text = readFileSync(skill.path, 'utf8');
+      const full = parseSkillText({
+        skillMdPath: skill.path,
+        skillDirName: skill.dir.split('/').pop() ?? skill.dir,
+        source: skill.source,
+        text,
+      });
+      content = full.content;
+    }
+
     const argumentNames = skillArgumentNames(skill.metadata);
-    const content = expandSkillParameters(skill.content, rawArgs, {
+    content = expandSkillParameters(content, rawArgs, {
       skillDir: skill.dir,
       sessionId: this.sessionId,
       argumentNames,
@@ -117,6 +172,15 @@ export class SessionSkillRegistry implements AgentSkillRegistry {
     );
   }
 
+  /**
+   * Skills that should be discoverable by the model via search or the skill
+   * listing. Same as {@link listInvocableSkills} but excludes sub-skills, which
+   * are hidden from the model and should only be reached through their parent.
+   */
+  private listSearchableSkills(): readonly SkillDefinition[] {
+    return this.listInvocableSkills().filter((skill) => skill.metadata.isSubSkill !== true);
+  }
+
   getSkillRoots(): readonly string[] {
     return [...this.roots];
   }
@@ -130,16 +194,55 @@ export class SessionSkillRegistry implements AgentSkillRegistry {
     return rendered.length === 0 ? 'No skills' : rendered;
   }
 
+  /**
+   * Search skills by free-text query. Delegates to the BM25 index.
+   * Lazily rebuilds the index if skills were registered since the last build.
+   */
+  searchSkills(query: string, limit?: number, minScore?: number): readonly SkillSearchResult[] {
+    if (this.indexDirty) {
+      this.searchIndex.build(this.listSearchableSkills());
+      this.indexDirty = false;
+    }
+    return this.searchIndex.search(query, limit, minScore);
+  }
+
   getModelSkillListing(): string {
-    const lines = ['DISREGARD any earlier skill listings. Current available skills:'];
-    const listing = renderGroupedSkills(
-      this.listInvocableSkills().filter((skill) => skill.metadata.isSubSkill !== true),
-      formatModelSkill,
+    if (this.modelSkillListingCache !== undefined) {
+      return this.modelSkillListingCache;
+    }
+
+    const invocable = this.listInvocableSkills().filter(
+      (skill) => skill.metadata.isSubSkill !== true,
     );
-    if (listing.length > 0) {
-      lines.push(listing);
+
+    // Auto-detect: small catalogue → legacy full listing.
+    // Large catalogue → compact/names-only + search-first.
+    let listing: string;
+    if (invocable.length <= this.compactListingThreshold) {
+      const lines = ['DISREGARD any earlier skill listings. Current available skills:'];
+      const rendered = renderGroupedSkills(invocable, formatModelSkill);
+      if (rendered.length > 0) lines.push(rendered);
+      listing = lines.length === 1 ? '' : lines.join('\n');
+    } else {
+      // Tier 2+3: Large catalogue — search-first.
+      const count = invocable.length;
+      const format = count > this.namesOnlyListingThreshold
+        ? formatNameOnlySkill
+        : formatCompactSkill;
+      const lines = [
+        `You have access to ${String(count)} registered skills.`,
+        'To find relevant skills, call the `Skill` tool with `action: "search"` and keywords from the user\'s request.',
+        'Do NOT guess skill names — always search first, then load with `action: "load"`.',
+        '',
+        'Skill names by scope:',
+      ];
+      const rendered = renderGroupedSkills(invocable, format);
+      if (rendered.length > 0) lines.push(rendered);
+      listing = lines.join('\n');
     }
-    return lines.length === 1 ? '' : lines.join('\n');
+
+    this.modelSkillListingCache = listing;
+    return listing;
   }
 }
 
@@ -183,6 +286,16 @@ function formatModelSkill(skill: SkillDefinition): readonly string[] {
   return lines;
 }
 
+/** Compact format: name + 80-char description, no path. */
+function formatCompactSkill(skill: SkillDefinition): readonly string[] {
+  return [`- ${skill.name}: ${truncate(skill.description, 80)}`];
+}
+
+/** Minimal format: name only. Used for catalogues > 300 skills. */
+function formatNameOnlySkill(skill: SkillDefinition): readonly string[] {
+  return [`- ${skill.name}`];
+}
+
 function truncate(value: string, max: number): string {
   return value.length > max ? value.slice(0, max) : value;
 }
diff --git a/packages/agent-core/src/skill/search.ts b/packages/agent-core/src/skill/search.ts
new file mode 100644
index 000000000..e877de151
--- /dev/null
+++ b/packages/agent-core/src/skill/search.ts
@@ -0,0 +1,308 @@
+/**
+ * SkillSearch — lightweight BM25 index for skill retrieval.
+ *
+ * Instead of injecting every skill into the system prompt, we build a
+ * compact inverted index at startup and expose a search() method that
+ * returns ranked results in <5 ms for 1 500+ skills.
+ *
+ * No external dependencies — pure TypeScript BM25 with Okapi TF-IDF.
+ */
+
+import type { SkillDefinition } from './types';
+
+// ── BM25 parameters ────────────────────────────────────────────────
+
+const K1 = 1.2; // term-frequency saturation
+const B = 0.75; // document-length normalisation
+
+// Field weights: name matches are much more likely to indicate a specialised
+// skill than description matches.
+const FIELD_WEIGHTS = {
+  name: 3.0,
+  aliases: 2.5,
+  whenToUse: 1.5,
+  description: 1.0,
+  tags: 0.8,
+  bodySnippet: 0.5,
+};
+
+// Bonus added when a query token directly matches a token in the skill name.
+const NAME_MATCH_BONUS = 0.25;
+
+// ── Synonym expansion (lightweight, no ML dependency) ───────────────
+
+const RAW_SYNONYMS: ReadonlyArray<readonly [string, readonly string[]]> = [
+  ['test', ['testing', 'spec', 'e2e', 'qa']],
+  ['testing', ['test', 'spec', 'e2e', 'qa']],
+  ['e2e', ['test', 'testing', 'playwright', 'cypress']],
+  ['deploy', ['deployment', 'ci', 'cd', 'shipping', 'release']],
+  ['debug', ['debugging', 'troubleshoot', 'diagnose']],
+  ['security', ['vulnerability', 'audit', 'penetration', 'appsec']],
+  ['refactor', ['refactoring', 'cleanup', 'restructure']],
+  ['docker', ['container', 'containerize', 'compose']],
+  ['database', ['db', 'sql', 'postgres', 'mysql', 'query']],
+  ['api', ['rest', 'graphql', 'endpoint', 'route']],
+  ['auth', ['authentication', 'authorization', 'login', 'oauth']],
+  ['performance', ['optimization', 'speed', 'latency', 'benchmark']],
+  ['monitor', ['observability', 'logging', 'metrics', 'tracing']],
+  ['ui', ['frontend', 'component', 'react', 'interface']],
+  ['backend', ['server', 'api', 'service']],
+  ['ai', ['ml', 'llm', 'model', 'inference']],
+  ['doc', ['documentation', 'readme', 'guide']],
+  ['i18n', ['internationalization', 'localization', 'translate', 'translation']],
+  ['translate', ['translation', 'i18n', 'localization']],
+  ['lint', ['format', 'prettier', 'eslint', 'style']],
+  ['type', ['typescript', 'typing', 'typecheck']],
+];
+
+function buildBidirectionalSynonyms(
+  raw: ReadonlyArray<readonly [string, readonly string[]]>,
+): ReadonlyMap<string, readonly string[]> {
+  const map = new Map<string, string[]>();
+  for (const [term, syns] of raw) {
+    for (const target of [term, ...syns]) {
+      const group = new Set<string>();
+      // Add every synonym of the target, including the original term.
+      for (const [src, dst] of raw) {
+        if (src === target || dst.includes(target)) {
+          group.add(src);
+          for (const s of dst) group.add(s);
+        }
+      }
+      group.delete(target);
+      const existing = map.get(target);
+      if (existing === undefined) {
+        map.set(target, [...group]);
+      } else {
+        for (const g of group) {
+          if (!existing.includes(g)) existing.push(g);
+        }
+      }
+    }
+  }
+  return map;
+}
+
+const SYNONYMS: ReadonlyMap<string, readonly string[]> = buildBidirectionalSynonyms(RAW_SYNONYMS);
+
+// Common English stopwords to ignore in skill text and queries.
+const STOPWORDS: ReadonlySet<string> = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by', 'from',
+  'as', 'is', 'was', 'are', 'were', 'be', 'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did',
+  'will', 'would', 'could', 'should', 'may', 'might', 'can', 'this', 'that', 'these', 'those', 'it',
+  'its', 'they', 'them', 'their', 'we', 'our', 'us', 'i', 'my', 'me', 'you', 'your',
+]);
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function splitCompoundIdentifier(token: string): string[] {
+  // camelCase / PascalCase
+  const camel = token.replaceAll(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  // snake_case / kebab-case
+  const parts = camel.replaceAll(/[_-]/g, ' ').split(/\s+/).filter(Boolean);
+  return parts.length > 1 ? parts : [token.toLowerCase()];
+}
+
+function tokenize(text: string, options: { removeStopwords?: boolean } = {}): string[] {
+  const raw = text
+    .toLowerCase()
+    .replaceAll(/[^\p{L}\p{N}_\-\s]/gu, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 0);
+
+  const expanded: string[] = [];
+  for (const token of raw) {
+    if (options.removeStopwords && STOPWORDS.has(token)) continue;
+    expanded.push(...splitCompoundIdentifier(token));
+  }
+  return expanded;
+}
+
+function expandWithSynonyms(tokens: readonly string[]): string[] {
+  const result = [...tokens];
+  for (const token of tokens) {
+    const syns = SYNONYMS.get(token);
+    if (syns !== undefined) {
+      for (const syn of syns) {
+        if (!result.includes(syn)) result.push(syn);
+      }
+    }
+  }
+  return result;
+}
+
+// ── Public types ────────────────────────────────────────────────────
+
+export interface SkillSearchResult {
+  readonly name: string;
+  readonly description: string;
+  readonly whenToUse: string;
+  readonly source: string;
+  readonly path: string;
+  readonly score: number;
+}
+
+// ── Index ───────────────────────────────────────────────────────────
+
+interface IndexEntry {
+  readonly skill: SkillDefinition;
+  readonly tokens: readonly string[];
+  readonly tokenSet: ReadonlySet<string>;
+  readonly nameTokens: ReadonlySet<string>;
+  readonly length: number;
+}
+
+interface PostingEntry {
+  readonly docIndex: number;
+  readonly tf: number;
+}
+
+export class SkillSearchIndex {
+  private entries: IndexEntry[] = [];
+  private invertedIndex = new Map<string, PostingEntry[]>();
+  private avgDocLength = 0;
+  private totalDocs = 0;
+
+  /**
+   * Build the index from a list of skill definitions.
+   * Runs once at startup; ~50 ms for 1 500 skills.
+   */
+  build(skills: readonly SkillDefinition[]): void {
+    this.entries = [];
+    this.invertedIndex.clear();
+
+    for (const skill of skills) {
+      const nameTokens = tokenize(skill.name, { removeStopwords: true });
+      const descriptionTokens = tokenize(skill.description, { removeStopwords: true });
+      const whenToUseTokens = tokenize(skill.metadata.whenToUse ?? '', { removeStopwords: true });
+      const bodySnippetTokens = tokenize(skill.bodySnippet ?? '', { removeStopwords: true });
+      const aliasesTokens = tokenize((skill.metadata.aliases ?? []).join(' '), { removeStopwords: true });
+      const tagsTokens = tokenize((skill.metadata.tags ?? []).join(' '), { removeStopwords: true });
+
+      // Weighted term frequency: a term appearing in the name contributes
+      // more than the same term appearing only in the description.
+      const weightedTf = new Map<string, number>();
+      const addTokens = (tokens: readonly string[], weight: number) => {
+        for (const tok of tokens) {
+          weightedTf.set(tok, (weightedTf.get(tok) ?? 0) + weight);
+        }
+      };
+      addTokens(nameTokens, FIELD_WEIGHTS.name);
+      addTokens(aliasesTokens, FIELD_WEIGHTS.aliases);
+      addTokens(whenToUseTokens, FIELD_WEIGHTS.whenToUse);
+      addTokens(descriptionTokens, FIELD_WEIGHTS.description);
+      addTokens(tagsTokens, FIELD_WEIGHTS.tags);
+      addTokens(bodySnippetTokens, FIELD_WEIGHTS.bodySnippet);
+
+      // Expand synonyms after field weighting so synonyms inherit the source
+      // field's weight and avoid double-counting.
+      const expandedTf = new Map<string, number>();
+      for (const [term, weight] of weightedTf) {
+        expandedTf.set(term, (expandedTf.get(term) ?? 0) + weight);
+        const syns = SYNONYMS.get(term);
+        if (syns !== undefined) {
+          for (const syn of syns) {
+            expandedTf.set(syn, (expandedTf.get(syn) ?? 0) + weight);
+          }
+        }
+      }
+
+      const expandedTokens = [...expandedTf.keys()];
+      const tokenSet = new Set(expandedTokens);
+      const docLength = [...expandedTf.values()].reduce((sum, w) => sum + w, 0);
+
+      const entry: IndexEntry = {
+        skill,
+        tokens: expandedTokens,
+        tokenSet,
+        nameTokens: new Set(nameTokens),
+        length: docLength,
+      };
+
+      const docIndex = this.entries.length;
+      this.entries.push(entry);
+
+      // Add to inverted index
+      for (const [term, tf] of expandedTf) {
+        const posting = this.invertedIndex.get(term);
+        const pEntry: PostingEntry = { docIndex, tf };
+        if (posting !== undefined) {
+          posting.push(pEntry);
+        } else {
+          this.invertedIndex.set(term, [pEntry]);
+        }
+      }
+    }
+
+    this.totalDocs = this.entries.length;
+    this.avgDocLength =
+      this.entries.reduce((sum, e) => sum + e.length, 0) / (this.totalDocs || 1);
+  }
+
+  search(query: string, limit = 10, minScore = 0): readonly SkillSearchResult[] {
+    if (this.totalDocs === 0) return [];
+
+    const baseQueryTokens = tokenize(query, { removeStopwords: true });
+    const queryTokens = expandWithSynonyms(baseQueryTokens);
+    if (queryTokens.length === 0) return [];
+
+    const scores = new Float64Array(this.totalDocs);
+
+    for (const term of queryTokens) {
+      const posting = this.invertedIndex.get(term);
+      if (posting === undefined) continue;
+
+      const n = posting.length;
+      const idf = Math.log((this.totalDocs - n + 0.5) / (n + 0.5) + 1);
+
+      for (const pe of posting) {
+        const docLen = this.entries[pe.docIndex]?.length ?? 0;
+        const numerator = pe.tf * (K1 + 1);
+        const denominator = pe.tf + K1 * (1 - B + B * (docLen / this.avgDocLength));
+        scores[pe.docIndex] = (scores[pe.docIndex] ?? 0) + idf * (numerator / denominator);
+      }
+    }
+
+    // Boost scores when a query token matches a skill name token. This rewards
+    // skills whose topic is literally named in the query, without requiring the
+    // model to know the exact skill name in advance.
+    for (let i = 0; i < this.totalDocs; i++) {
+      const entry = this.entries[i];
+      if (entry === undefined) continue;
+      let nameMatches = 0;
+      for (const token of baseQueryTokens) {
+        if (entry.nameTokens.has(token)) nameMatches += 1;
+      }
+      if (nameMatches > 0) {
+        scores[i] = (scores[i] ?? 0) + nameMatches * NAME_MATCH_BONUS;
+      }
+    }
+
+    const candidates: Array<{ index: number; score: number }> = [];
+    for (let i = 0; i < this.totalDocs; i++) {
+      const s = scores[i] ?? 0;
+      if (s > minScore) {
+        candidates.push({ index: i, score: s });
+      }
+    }
+
+    candidates.sort((a, b) => b.score - a.score);
+
+    return candidates.slice(0, limit).map(({ index, score }) => {
+      const entry = this.entries[index]!;
+      return {
+        name: entry.skill.name,
+        description: entry.skill.description.slice(0, 200),
+        whenToUse: entry.skill.metadata.whenToUse ?? '',
+        source: entry.skill.source,
+        path: entry.skill.path,
+        score: Math.round(score * 100) / 100,
+      };
+    });
+  }
+
+  /** Total number of indexed skills. */
+  get size(): number {
+    return this.totalDocs;
+  }
+}
diff --git a/packages/agent-core/src/skill/types.ts b/packages/agent-core/src/skill/types.ts
index 7e030adf9..d6799b8e3 100644
--- a/packages/agent-core/src/skill/types.ts
+++ b/packages/agent-core/src/skill/types.ts
@@ -9,6 +9,8 @@ export interface SkillMetadata {
   readonly isSubSkill?: boolean | undefined;
   readonly safe?: boolean | undefined;
   readonly arguments?: readonly unknown[] | string | undefined;
+  readonly aliases?: readonly string[] | undefined;
+  readonly tags?: readonly string[] | undefined;
   readonly [key: string]: unknown;
 }
 
@@ -18,6 +20,7 @@ export interface SkillDefinition {
   readonly path: string;
   readonly dir: string;
   readonly content: string;
+  readonly bodySnippet?: string;
   readonly metadata: SkillMetadata;
   readonly source: SkillSource;
   readonly plugin?: SkillPluginContext;
diff --git a/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md
index bc67f43f5..ed29097c9 100644
--- a/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md
+++ b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md
@@ -1 +1,11 @@
-Invoke a registered skill from the current skill listing. BLOCKING REQUIREMENT: when a skill from the listing matches the user's request, you MUST call this tool (not free-form text). Do NOT call the same skill repeatedly inside one turn — recursive depth is capped at {{ MAX_SKILL_QUERY_DEPTH }}.
\ No newline at end of file
+Two actions available:
+
+**Search** (`action: "search"`): Find relevant skills by keywords. Returns ranked results.
+Use this when you need to discover skills that match the user's request.
+Example: user says "help me write e2e tests" → `{"action":"search","query":"e2e test playwright"}`
+
+**Load** (`action: "load"`, default): Load a skill's full instructions into context.
+Only call after you know the exact skill name (from search results or the skill listing).
+BLOCKING REQUIREMENT: when a skill matches the user's request, you MUST load it (not free-form text).
+
+Do NOT call the same skill repeatedly inside one turn — recursive depth is capped at {{ MAX_SKILL_QUERY_DEPTH }}.
diff --git a/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts
index 2ee932dd0..dece8a412 100644
--- a/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts
+++ b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts
@@ -44,13 +44,22 @@ export class NestedSkillTooDeepError extends Error {
 }
 
 export interface SkillToolInput {
-  skill: string;
+  skill?: string;
   args?: string;
+  /** "load" (default) loads a skill's full instructions; "search" searches the catalog. */
+  action?: 'load' | 'search';
+  /** Search query — required when action is "search". */
+  query?: string;
+  /** Max search results (default 10, max 20). */
+  limit?: number;
 }
 
 export const SkillToolInputSchema: z.ZodType<SkillToolInput> = z.object({
-  skill: z.string(),
+  skill: z.string().optional(),
   args: z.string().optional(),
+  action: z.enum(['load', 'search']).optional(),
+  query: z.string().optional(),
+  limit: z.number().int().min(1).max(20).optional(),
 });
 
 export interface SkillToolOptions {
@@ -79,10 +88,10 @@ export class SkillTool implements BuiltinTool<SkillToolInput> {
 
   resolveExecution(args: SkillToolInput): ToolExecution {
     return {
-      description: `Invoke skill ${args.skill}`,
-      display: { kind: 'skill_call', skill_name: args.skill, args: args.args },
+      description: `Invoke skill ${args.skill ?? '(search)'}`,
+      display: { kind: 'skill_call', skill_name: args.skill ?? '', args: args.args },
       approvalRule: this.name,
-      matchesRule: (ruleArgs) => matchesGlobRuleSubject(ruleArgs, args.skill),
+      matchesRule: (ruleArgs) => matchesGlobRuleSubject(ruleArgs, args.skill ?? ''),
       execute: () => this.execution(args),
     };
   }
@@ -95,6 +104,36 @@ export class SkillTool implements BuiltinTool<SkillToolInput> {
   }
 
   private async execution(args: SkillToolInput): Promise<ExecutableToolResult> {
+    const action = args.action ?? 'load';
+
+    // ── Search action ──────────────────────────────────────────────
+    if (action === 'search') {
+      const query = args.query ?? args.skill;
+      if (!query || query.trim().length === 0) {
+        return errorResult('A search query is required. Provide "query" or "skill".');
+      }
+      const skills = this.agent.skills;
+      if (skills === null) {
+        return errorResult('No skills are registered.');
+      }
+      const results = skills.registry.searchSkills(query, args.limit ?? 10);
+      if (results.length === 0) {
+        return { output: `No skills found matching "${query}". Try broader keywords.` };
+      }
+      const lines = [`Found ${String(results.length)} skill(s) matching "${query}":`];
+      for (const r of results) {
+        const wt = r.whenToUse ? ` (When: ${r.whenToUse})` : '';
+        lines.push(`- ${r.name}: ${r.description}${wt}  [score: ${String(r.score)}]`);
+      }
+      lines.push('', 'Call again with action:"load" and the skill name to load its instructions.');
+      return { output: lines.join('\n') };
+    }
+
+    // ── Load action (original behaviour) ───────────────────────────
+    const skillName = args.skill;
+    if (!skillName) {
+      return errorResult('A skill name is required for action "load". Provide the "skill" parameter.');
+    }
     // Recursion hard cap. Once `currentDepth` has reached
     // MAX_SKILL_QUERY_DEPTH, firing another Skill call would push the
     // child to depth+1 which violates the invariant. Throw a structured
@@ -102,22 +141,22 @@ export class SkillTool implements BuiltinTool<SkillToolInput> {
     // "LLM mis-dispatched" from "safety net fired".
     const currentDepth = this.options.initialQueryDepth ?? this.options.queryDepth ?? 0;
     if (currentDepth >= MAX_SKILL_QUERY_DEPTH) {
-      throw new NestedSkillTooDeepError(MAX_SKILL_QUERY_DEPTH, args.skill);
+      throw new NestedSkillTooDeepError(MAX_SKILL_QUERY_DEPTH, skillName);
     }
 
     const skills = this.agent.skills;
     if (skills === null) {
-      return errorResult(`Skill "${args.skill}" not found in the current skill listing.`);
+      return errorResult(`Skill "${skillName}" not found in the current skill listing.`);
     }
-    const skill = skills.registry.getSkill(args.skill);
+    const skill = skills.registry.getSkill(skillName);
     if (skill === undefined) {
-      return errorResult(`Skill "${args.skill}" not found in the current skill listing.`);
+      return errorResult(`Skill "${skillName}" not found in the current skill listing.`);
     }
     if (skill.metadata.disableModelInvocation === true) {
       // Keep the exact wording "can only be triggered by the user" so
       // contract audits and integration tests stay deterministic.
       return errorResult(
-        `Skill "${args.skill}" can only be triggered by the user (model invocation is disabled).`,
+        `Skill "${skillName}" can only be triggered by the user (model invocation is disabled).`,
       );
     }
 
diff --git a/packages/agent-core/test/agent/skill-tool-manager.test.ts b/packages/agent-core/test/agent/skill-tool-manager.test.ts
index 51b42a74e..2d91a247b 100644
--- a/packages/agent-core/test/agent/skill-tool-manager.test.ts
+++ b/packages/agent-core/test/agent/skill-tool-manager.test.ts
@@ -136,6 +136,7 @@ describe('ToolManager SkillTool registration', () => {
       listInvocableSkills: () => [skill],
       getSkillRoots: () => ['/skills/review'],
       getModelSkillListing: () => '- review: desc for review',
+      searchSkills: () => [],
     };
 
     const agent = makeAgent(skills);
diff --git a/packages/agent-core/test/skill/integration-proof.test.ts b/packages/agent-core/test/skill/integration-proof.test.ts
new file mode 100644
index 000000000..88036731d
--- /dev/null
+++ b/packages/agent-core/test/skill/integration-proof.test.ts
@@ -0,0 +1,119 @@
+/**
+ * Integration proof: capture what the LLM actually sees — system prompt,
+ * tool definitions, and end-to-end skill search with real fixture skills.
+ *
+ * Uses a temporary fixture directory (not ~/.kimi/skills) so tests are
+ * portable across CI and developer machines.
+ */
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import { SessionSkillRegistry } from '../../src/skill';
+import type { SkillRoot } from '../../src/skill';
+import { join } from 'node:path';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { performance } from 'node:perf_hooks';
+
+let FIXTURE_DIR: string;
+
+beforeAll(() => {
+  FIXTURE_DIR = mkdtempSync(join(tmpdir(), 'kimi-skill-test-'));
+
+  // Create 350 fixture skills (enough to trigger names-only tier at >300)
+  for (let i = 0; i < 350; i++) {
+    const name = `test-skill-${String(i).padStart(3, '0')}`;
+    const dir = join(FIXTURE_DIR, name);
+    mkdirSync(dir, { recursive: true });
+    const domain = ['docker', 'react', 'security', 'database', 'api', 'playwright', 'testing', 'deploy'][i % 8];
+    writeFileSync(
+      join(dir, 'SKILL.md'),
+      `---\nname: ${name}\ndescription: ${domain} automation and best practices for skill ${String(i)}\nwhenToUse: When working on ${domain} tasks\n---\n\n# ${name}\n\nDetailed instructions for ${domain} skill ${String(i)}.\n\n\`\`\`bash\n# Example usage\necho "running ${name}"\n\`\`\`\n`,
+    );
+  }
+});
+
+afterAll(() => {
+  rmSync(FIXTURE_DIR, { recursive: true, force: true });
+});
+
+describe('INTEGRATION: what the LLM actually sees', () => {
+  it('auto-detects names-only tier for 350 fixture skills', async () => {
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: FIXTURE_DIR, source: 'user' }]);
+
+    const listing = registry.getModelSkillListing();
+
+    console.log('\n=== Auto-detected: names-only tier (350 skills) ===');
+    console.log(`Listing size: ${listing.length.toLocaleString()} chars ≈ ${Math.round(listing.length / 4).toLocaleString()} tokens`);
+    console.log(`Contains "registered skills": ${listing.includes('registered skills')}`);
+    console.log(`Contains "search": ${listing.includes('search')}`);
+
+    // 350 > 300 → names-only tier with search instructions
+    expect(listing).toContain('registered skills');
+    expect(listing).toContain('search');
+    expect(listing).not.toContain('When to use:');
+    expect(listing).not.toContain('SKILL.md');
+  });
+
+  it('Skill tool definition includes search action description', async () => {
+    const fs = await import('node:fs');
+    const REPO_ROOT = join(import.meta.dirname ?? __dirname, '..', '..', '..', '..');
+    const toolMd = fs.readFileSync(
+      join(REPO_ROOT, 'packages/agent-core/src/tools/builtin/collaboration/skill-tool.md'),
+      'utf-8',
+    );
+
+    console.log('\n=== Skill Tool Definition ===');
+    console.log(toolMd);
+
+    expect(toolMd).toContain('search');
+    expect(toolMd).toContain('load');
+    expect(toolMd).toContain('action');
+  });
+
+  it('system.md instructs search-first workflow', async () => {
+    const fs = await import('node:fs');
+    const REPO_ROOT = join(import.meta.dirname ?? __dirname, '..', '..', '..', '..');
+    const systemMd = fs.readFileSync(
+      join(REPO_ROOT, 'packages/agent-core/src/profile/default/system.md'),
+      'utf-8',
+    );
+
+    const skillsIdx = systemMd.indexOf('# Skills');
+    const skillsSection = systemMd.slice(skillsIdx, skillsIdx + 1500);
+
+    expect(skillsSection).toContain('search');
+    expect(skillsSection).toContain('action: "search"');
+    expect(skillsSection).toContain('action: "load"');
+  });
+
+  it('end-to-end: search finds the right skill for a real task', async () => {
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: FIXTURE_DIR, source: 'user' }]);
+
+    console.log('\n=== End-to-End Simulation ===');
+
+    const userRequest = 'deploy docker containers';
+    console.log(`User: "${userRequest}"`);
+
+    const t0 = performance.now();
+    const results = registry.searchSkills(userRequest, 5);
+    const tSearch = performance.now() - t0;
+    console.log(`\nSearch (${tSearch.toFixed(1)}ms):`);
+    for (const r of results) {
+      console.log(`  ${r.name} (score: ${r.score}) - ${r.description.slice(0, 60)}`);
+    }
+
+    const picked = results[0]!;
+    console.log(`\nModel picks: "${picked.name}"`);
+    expect(picked.description).toMatch(/deploy|docker/);
+
+    // Verify lazy content load works
+    const skill = registry.getSkill(picked.name);
+    expect(skill).toBeDefined();
+
+    const rendered = registry.renderSkillPrompt(skill!, '');
+    console.log(`Rendered: ${rendered.length} chars`);
+    expect(rendered.length).toBeGreaterThan(0);
+    expect(rendered).toContain('Detailed instructions');
+  });
+});
diff --git a/packages/agent-core/test/skill/parser.test.ts b/packages/agent-core/test/skill/parser.test.ts
index 694ff640f..b713b935b 100644
--- a/packages/agent-core/test/skill/parser.test.ts
+++ b/packages/agent-core/test/skill/parser.test.ts
@@ -54,14 +54,27 @@ describe('skill parser', () => {
     });
   });
 
-  it('falls back to the first non-empty body line as description when frontmatter is absent', async () => {
+  it('falls back to the first body sentence as description when frontmatter is absent', async () => {
     const root = await makeSkillsRoot();
-    await writeFlat(root, 'plain.md', ['', '', 'This is the headline description.', '', 'More body text here.']);
+    await writeFlat(root, 'plain.md', ['', '', '# This is a heading.', '', 'More body text here.']);
 
     const skills = await discoverSkills({ roots: [userRoot(root)] });
     expect(skills).toHaveLength(1);
     expect(skills[0]?.name).toBe('plain');
-    expect(skills[0]?.description.toLowerCase()).toContain('headline description');
+    expect(skills[0]?.description).toBe('# This is a heading.');
+  });
+
+  it('prefers the first sentence over a heading if a sentence exists before any heading', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'lead-sentence.md', [
+      '',
+      'This is the lead sentence. Then more text.',
+      '',
+      '# Heading',
+    ]);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills[0]?.description).toBe('This is the lead sentence.');
   });
 
   it('prefers frontmatter description over body first-line fallback', async () => {
@@ -135,6 +148,61 @@ describe('skill parser', () => {
     expect(skills).toEqual([]);
     expect(warnings.some((message) => message.includes('Invalid frontmatter'))).toBe(true);
   });
+
+  it('lazy frontmatter parsing preserves CRLF frontmatter fences', async () => {
+    const root = await makeSkillsRoot();
+    const content = ['---', 'name: crlf-skill', 'description: A CRLF skill', '---', '', '# Body'].join(
+      '\r\n',
+    );
+    const dir = path.join(root, 'crlf-skill');
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, 'SKILL.md'), content);
+
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([userRoot(root)]);
+
+    const skill = registry.getSkill('crlf-skill');
+    expect(skill).toBeDefined();
+    expect(skill?.description).toBe('A CRLF skill');
+    expect(skill?.content).toBe('\u0000LAZY');
+
+    // Full body should still render correctly after lazy load.
+    const rendered = registry.renderSkillPrompt(skill!, '');
+    expect(rendered).toContain('# Body');
+  });
+
+  it('lazy frontmatter parsing derives flat-skill description from the body', async () => {
+    const root = await makeSkillsRoot();
+    await writeFile(
+      path.join(root, 'flat-derived.md'),
+      ['---', 'name: flat-derived', '---', '', 'Body headline for the skill.'].join('\n'),
+    );
+
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([userRoot(root)]);
+
+    const skill = registry.getSkill('flat-derived');
+    expect(skill).toBeDefined();
+    expect(skill?.description).toBe('Body headline for the skill.');
+    expect(skill?.content).toBe('\u0000LAZY');
+  });
+
+  it('captures a body snippet during lazy frontmatter parsing', async () => {
+    const root = await makeSkillsRoot();
+    const dir = path.join(root, 'snippet-skill');
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      path.join(dir, 'SKILL.md'),
+      ['---', 'name: snippet-skill', 'description: A skill', '---', '', '# Overview', '', 'Use this for graphql and rest endpoints.'].join('\n'),
+    );
+
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([userRoot(root)]);
+
+    const skill = registry.getSkill('snippet-skill');
+    expect(skill).toBeDefined();
+    expect(skill?.bodySnippet).toContain('graphql');
+  });
 });
 
 describe('skill parameter expansion', () => {
diff --git a/packages/agent-core/test/skill/registry.test.ts b/packages/agent-core/test/skill/registry.test.ts
index b7c680474..b41d43e47 100644
--- a/packages/agent-core/test/skill/registry.test.ts
+++ b/packages/agent-core/test/skill/registry.test.ts
@@ -96,6 +96,158 @@ describe('skill registry prompt rendering', () => {
   });
 });
 
+describe('skill registry search', () => {
+  it('searchSkills returns relevant results by name and description', () => {
+    const registry = makeRegistry([
+      makeSkill('playwright-e2e', 'user', 'End-to-end testing with Playwright browser automation'),
+      makeSkill('docker-expert', 'user', 'Docker containerization and deployment'),
+      makeSkill('react-ui', 'user', 'React component patterns and hooks'),
+    ]);
+
+    const results = registry.searchSkills('playwright browser test');
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0]!.name).toBe('playwright-e2e');
+  });
+
+  it('searchSkills finds by synonym expansion', () => {
+    const registry = makeRegistry([
+      makeSkill('container-build', 'user', 'Docker container build optimization'),
+      makeSkill('api-design', 'user', 'REST API design patterns'),
+    ]);
+
+    // "container" is a synonym of "docker"
+    const results = registry.searchSkills('container image build');
+    expect(results.some((r) => r.name === 'container-build')).toBe(true);
+  });
+
+  it('searchSkills returns empty for nonsense queries', () => {
+    const registry = makeRegistry([makeSkill('alpha', 'user', 'does things')]);
+    const results = registry.searchSkills('xyzzy plugh foobar');
+    expect(results.length).toBe(0);
+  });
+
+  it('searchSkills lazily rebuilds index after register()', () => {
+    const registry = new SessionSkillRegistry();
+    registry.register(makeSkill('initial-skill', 'user', 'initial'));
+
+    const before = registry.searchSkills('initial');
+    expect(before.length).toBe(1);
+
+    registry.register(makeSkill('added-later', 'user', 'added after first search'));
+
+    const after = registry.searchSkills('added');
+    expect(after.length).toBe(1);
+    expect(after[0]!.name).toBe('added-later');
+  });
+
+  it('searchSkills ranks name matches above description-only matches', () => {
+    const registry = makeRegistry([
+      makeSkill('playwright-e2e', 'user', 'End-to-end testing toolkit'),
+      makeSkill('generic-browser', 'user', 'Browser automation with Playwright and Selenium'),
+    ]);
+
+    const results = registry.searchSkills('playwright');
+    expect(results[0]!.name).toBe('playwright-e2e');
+  });
+
+  it('searchSkills expands synonyms bidirectionally', () => {
+    const registry = makeRegistry([
+      makeSkill('container-build', 'user', 'Docker container build optimization'),
+      makeSkill('api-design', 'user', 'REST API design patterns'),
+    ]);
+
+    // "docker" is a synonym of "container", and the reverse mapping is now automatic.
+    const results = registry.searchSkills('docker image build');
+    expect(results.some((r) => r.name === 'container-build')).toBe(true);
+  });
+
+  it('searchSkills ignores stopwords in the query', () => {
+    const registry = makeRegistry([
+      makeSkill('docker-expert', 'user', 'Docker containerization and deployment'),
+      makeSkill('react-ui', 'user', 'React component patterns and hooks'),
+    ]);
+
+    const results = registry.searchSkills('the docker container');
+    expect(results[0]!.name).toBe('docker-expert');
+  });
+
+  it('searchSkills excludes sub-skills from results', () => {
+    const registry = makeRegistry([
+      makeSkill('parent', 'user', 'Parent skill'),
+      makeSkill('parent.child', 'user', 'Hidden child skill', undefined, { isSubSkill: true }),
+    ]);
+
+    const results = registry.searchSkills('child');
+    expect(results.some((r) => r.name === 'parent.child')).toBe(false);
+  });
+
+  it('getModelSkillListing caches the result and invalidates on register()', () => {
+    const skills = Array.from({ length: 100 }, (_, i) =>
+      makeSkill(`skill-${String(i)}`, 'user', `Description ${String(i)}`),
+    );
+    const registry = makeRegistry(skills);
+
+    const first = registry.getModelSkillListing();
+    const second = registry.getModelSkillListing();
+    expect(second).toBe(first);
+
+    registry.register(makeSkill('new-skill', 'user', 'A newly added skill'));
+    const after = registry.getModelSkillListing();
+    expect(after).not.toBe(first);
+    expect(after).toContain('101 registered skills');
+  });
+});
+
+describe('getModelSkillListing tiers', () => {
+  it('uses legacy full listing for ≤80 skills (auto-detect)', () => {
+    const skills = Array.from({ length: 50 }, (_, i) =>
+      makeSkill(`skill-${String(i)}`, 'user', `Description ${String(i)}`),
+    );
+    const registry = makeRegistry(skills);
+
+    const listing = registry.getModelSkillListing();
+    expect(listing).toContain('DISREGARD');
+    expect(listing).toContain('Description');
+  });
+
+  it('uses compact listing for 81–300 skills (auto-detect)', () => {
+    const skills = Array.from({ length: 100 }, (_, i) =>
+      makeSkill(`skill-${String(i)}`, 'user', `Description ${String(i)}`),
+    );
+    const registry = makeRegistry(skills);
+
+    const listing = registry.getModelSkillListing();
+    expect(listing).toContain('100 registered skills');
+    expect(listing).toContain('search');
+    expect(listing).not.toContain('DISREGARD');
+    expect(listing).not.toContain('SKILL.md');
+  });
+
+  it('uses names-only listing for 300+ skills (auto-detect)', () => {
+    const skills = Array.from({ length: 400 }, (_, i) =>
+      makeSkill(`skill-${String(i)}`, 'user', `Description for skill ${String(i)}`),
+    );
+    const registry = makeRegistry(skills);
+
+    const listing = registry.getModelSkillListing();
+    expect(listing).toContain('400 registered skills');
+    expect(listing).not.toContain('Description for skill');
+    expect(listing).toContain('skill-0');
+  });
+
+  it('respects custom compact listing threshold', () => {
+    const skills = Array.from({ length: 50 }, (_, i) =>
+      makeSkill(`skill-${String(i)}`, 'user', `Description ${String(i)}`),
+    );
+    const registry = new SessionSkillRegistry({ compactListingThreshold: 30 });
+    for (const skill of skills) registry.register(skill);
+
+    const listing = registry.getModelSkillListing();
+    expect(listing).toContain('50 registered skills');
+    expect(listing).not.toContain('DISREGARD');
+  });
+});
+
 function makeRegistry(skills: readonly SkillDefinition[]): SessionSkillRegistry {
   const registry = new SessionSkillRegistry();
   for (const skill of skills) registry.register(skill);
@@ -107,6 +259,7 @@ function makeSkill(
   source: SkillSource,
   description = 'desc',
   skillPath?: string,
+  metadataOverrides: Partial<SkillDefinition['metadata']> = {},
 ): SkillDefinition {
   const finalPath = skillPath ?? `/tmp/${source}/${name}/SKILL.md`;
   return {
@@ -115,7 +268,7 @@ function makeSkill(
     path: finalPath,
     dir: finalPath.replace(/\/SKILL\.md$/, ''),
     content: '',
-    metadata: { type: 'prompt' },
+    metadata: { type: 'prompt', ...metadataOverrides },
     source,
   };
 }
diff --git a/packages/agent-core/test/skill/scanner.test.ts b/packages/agent-core/test/skill/scanner.test.ts
index 8274f0056..d98c64d56 100644
--- a/packages/agent-core/test/skill/scanner.test.ts
+++ b/packages/agent-core/test/skill/scanner.test.ts
@@ -865,8 +865,8 @@ describe('resolveSkillRoots extra dirs', () => {
       },
     ]);
 
-    expect(registry.getSkill('using-superpowers')?.content).toBe('project body');
-    expect(registry.getPluginSkill('superpowers', 'using-superpowers')?.content).toBe(
+    expect(registry.renderSkillPrompt(registry.getSkill('using-superpowers')!, '')).toContain('project body');
+    expect(registry.renderSkillPrompt(registry.getPluginSkill('superpowers', 'using-superpowers')!, '')).toContain(
       'plugin body',
     );
   });
diff --git a/packages/agent-core/test/skill/search.test.ts b/packages/agent-core/test/skill/search.test.ts
new file mode 100644
index 000000000..ab58918db
--- /dev/null
+++ b/packages/agent-core/test/skill/search.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import { SkillSearchIndex } from '../../src/skill/search';
+
+function makeSkill(name: string, description: string, whenToUse = '') {
+  return {
+    name,
+    description,
+    path: `/tmp/${name}/SKILL.md`,
+    dir: `/tmp/${name}`,
+    content: '',
+    metadata: { type: 'prompt', whenToUse },
+    source: 'user' as const,
+  };
+}
+
+describe('SkillSearchIndex tokenization', () => {
+  it('tokenizes Korean descriptions', () => {
+    const index = new SkillSearchIndex();
+    index.build([makeSkill('korean-skill', '한국어 스킬 설명입니다')]);
+    const results = index.search('한국어 스킬');
+    expect(results).toHaveLength(1);
+    expect(results[0]?.name).toBe('korean-skill');
+  });
+
+  it('tokenizes Portuguese accented words', () => {
+    const index = new SkillSearchIndex();
+    index.build([makeSkill('pt-skill', 'Otimização de performance com cache')]);
+    const results = index.search('otimização');
+    expect(results).toHaveLength(1);
+    expect(results[0]?.name).toBe('pt-skill');
+  });
+
+  it('returns empty when no result meets the minimum score threshold', () => {
+    const index = new SkillSearchIndex();
+    index.build([makeSkill('docker-expert', 'Docker containerization')]);
+    const results = index.search('react component', 10, 0.1);
+    expect(results).toHaveLength(0);
+  });
+
+  it('returns low-relevance results when threshold is zero', () => {
+    const index = new SkillSearchIndex();
+    index.build([makeSkill('docker-expert', 'Docker containerization')]);
+    const results = index.search('react container', 10, 0);
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('finds skills by body snippet keywords', () => {
+    const index = new SkillSearchIndex();
+    index.build([
+      {
+        ...makeSkill('api-skill', 'API design patterns'),
+        bodySnippet: 'Covers graphql and rest endpoints.',
+      },
+    ]);
+    const results = index.search('graphql');
+    expect(results.some((r) => r.name === 'api-skill')).toBe(true);
+  });
+
+  it('matches skills by aliases metadata', () => {
+    const index = new SkillSearchIndex();
+    index.build([
+      {
+        ...makeSkill('containers', 'Container best practices'),
+        metadata: { type: 'prompt', aliases: ['docker', 'podman'] },
+      },
+    ]);
+    const results = index.search('docker');
+    expect(results.some((r) => r.name === 'containers')).toBe(true);
+  });
+
+  it('matches skills by tags metadata', () => {
+    const index = new SkillSearchIndex();
+    index.build([
+      {
+        ...makeSkill('auth-skill', 'Authentication patterns'),
+        metadata: { type: 'prompt', tags: ['oauth', 'jwt'] },
+      },
+    ]);
+    const results = index.search('jwt');
+    expect(results.some((r) => r.name === 'auth-skill')).toBe(true);
+  });
+
+  it('ranks name matches above description-only matches', () => {
+    const index = new SkillSearchIndex();
+    index.build([
+      makeSkill('playwright-e2e', 'End-to-end testing toolkit'),
+      makeSkill('generic-browser', 'Browser automation with Playwright and Selenium'),
+    ]);
+    const results = index.search('playwright');
+    expect(results[0]?.name).toBe('playwright-e2e');
+  });
+
+  it('expands synonyms bidirectionally', () => {
+    const index = new SkillSearchIndex();
+    index.build([makeSkill('container-build', 'Docker container build optimization')]);
+    const results = index.search('docker image build');
+    expect(results.some((r) => r.name === 'container-build')).toBe(true);
+  });
+
+  it('ignores stopwords in the query', () => {
+    const index = new SkillSearchIndex();
+    index.build([makeSkill('docker-expert', 'Docker containerization and deployment')]);
+    const results = index.search('the docker container');
+    expect(results[0]?.name).toBe('docker-expert');
+  });
+});
diff --git a/packages/agent-core/test/skill/smoke.test.ts b/packages/agent-core/test/skill/smoke.test.ts
new file mode 100644
index 000000000..0c9948e8f
--- /dev/null
+++ b/packages/agent-core/test/skill/smoke.test.ts
@@ -0,0 +1,171 @@
+/**
+ * Smoke test: exercises real code paths with actual skill files.
+ * Proves the feature works end-to-end without LLM API calls.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { SessionSkillRegistry } from '../../src/skill';
+import { LAZY_CONTENT_SENTINEL } from '../../src/skill/parser';
+import { SkillSearchIndex } from '../../src/skill/search';
+import { SkillTool, SkillToolInputSchema } from '../../src/tools/builtin/collaboration/skill-tool';
+import { join } from 'node:path';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+let FIXTURE_DIR: string;
+const SKILL_COUNT = 350;
+
+beforeAll(() => {
+  FIXTURE_DIR = mkdtempSync(join(tmpdir(), 'smoke-'));
+  for (let i = 0; i < SKILL_COUNT; i++) {
+    const name = `skill-${String(i).padStart(3, '0')}`;
+    const dir = join(FIXTURE_DIR, name);
+    mkdirSync(dir, { recursive: true });
+    const domain = ['docker', 'playwright', 'security', 'react', 'postgres', 'github-actions', 'rest-api', 'machine-learning'][i % 8];
+    writeFileSync(
+      join(dir, 'SKILL.md'),
+      `---\nname: ${name}\ndescription: Best practices for ${domain} development and automation\nwhenToUse: When the user needs help with ${domain}\n---\n\n# ${name}\n\nFollow these steps for ${domain}:\n\n1. Analyze the current setup\n2. Apply best practices\n3. Verify the result\n\n\`\`\`bash\n# ${domain} example command\nnpm run ${domain}\n\`\`\`\n`,
+    );
+  }
+});
+
+describe('SMOKE: end-to-end skill search', () => {
+
+  it('registry loads skills and auto-detects tier', async () => {
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: FIXTURE_DIR, source: 'user' }]);
+
+    const all = registry.listSkills();
+    const invocable = registry.listInvocableSkills();
+    expect(all.length).toBe(SKILL_COUNT);
+    expect(invocable.length).toBe(SKILL_COUNT);
+
+    // 350 > 300 → names-only tier
+    const listing = registry.getModelSkillListing();
+    expect(listing).toContain(`${SKILL_COUNT} registered skills`);
+    expect(listing).toContain('search');
+    expect(listing).not.toContain('SKILL.md');
+    expect(listing).not.toContain('When to use:');
+
+    console.log(`\n✅ Tier auto-detected: names-only (${SKILL_COUNT} skills)`);
+    console.log(`   Listing: ${listing.length} chars ≈ ${Math.round(listing.length / 4)} tokens`);
+  });
+
+  it('lazy content: content is sentinel after load, loaded after renderSkillPrompt', async () => {
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: FIXTURE_DIR, source: 'user' }]);
+
+    const skill = registry.getSkill('skill-000');
+    expect(skill).toBeDefined();
+    expect(skill!.content).toBe(LAZY_CONTENT_SENTINEL);
+
+    const rendered = registry.renderSkillPrompt(skill!, '');
+    expect(rendered).toContain('Follow these steps');
+    expect(rendered).toContain('npm run');
+
+    console.log('✅ Lazy load: sentinel → readFileSync → content loaded');
+    console.log(`   skill-000 content: "${skill!.content.slice(0, 30)}..." → rendered ${rendered.length} chars`);
+  });
+
+  it('BM25 search returns correct results', async () => {
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: FIXTURE_DIR, source: 'user' }]);
+
+    const queries = [
+      ['docker container build', 'docker'],
+      ['playwright browser test', 'playwright'],
+      ['security vulnerability audit', 'security'],
+      ['react hooks component', 'react'],
+      ['postgres sql query', 'postgres'],
+      ['github actions CI/CD pipeline', 'github-actions'],
+      ['REST API endpoint design', 'rest-api'],
+      ['machine learning model training', 'machine-learning'],
+    ] as const;
+
+    console.log('\n✅ BM25 search results:');
+    let allCorrect = true;
+    for (const [query, expectedDomain] of queries) {
+      const results = registry.searchSkills(query, 3);
+      const topDesc = results[0]?.description ?? '';
+      const hit = topDesc.includes(expectedDomain);
+      if (!hit) allCorrect = false;
+      console.log(`   "${query}" → ${results[0]?.name} (${hit ? '✅' : '❌'} ${expectedDomain})`);
+    }
+    expect(allCorrect).toBe(true);
+  });
+
+  it('Skill tool schema accepts search without skill name', () => {
+    // search-only: no skill required
+    const r1 = SkillToolInputSchema.safeParse({ action: 'search', query: 'docker' });
+    expect(r1.success).toBe(true);
+
+    // load with skill: works
+    const r2 = SkillToolInputSchema.safeParse({ skill: 'skill-000' });
+    expect(r2.success).toBe(true);
+
+    // empty: valid (skill optional)
+    const r3 = SkillToolInputSchema.safeParse({});
+    expect(r3.success).toBe(true);
+
+    console.log('✅ Schema: search without skill name accepted');
+  });
+
+  it('CRLF frontmatter parsed correctly', async () => {
+    const crlfDir = mkdtempSync(join(tmpdir(), 'crlf-'));
+    const name = 'crlf-skill';
+    const dir = join(crlfDir, name);
+    mkdirSync(dir, { recursive: true });
+    // Write with CRLF line endings
+    writeFileSync(
+      join(dir, 'SKILL.md'),
+      `---\r\nname: ${name}\r\ndescription: CRLF test skill\r\n---\r\n\r\n# CRLF Skill\r\n\r\nBody content here.\r\n`,
+    );
+
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: crlfDir, source: 'user' }]);
+
+    const skill = registry.getSkill(name);
+    expect(skill).toBeDefined();
+    expect(skill!.name).toBe(name);
+    expect(skill!.description).toBe('CRLF test skill');
+
+    // Lazy load should work
+    const rendered = registry.renderSkillPrompt(skill!, '');
+    expect(rendered).toContain('Body content here');
+
+    rmSync(crlfDir, { recursive: true, force: true });
+    console.log('✅ CRLF frontmatter: parsed + lazy loaded correctly');
+  });
+
+  it('model flow: search → pick → load → render', async () => {
+    const registry = new SessionSkillRegistry();
+    await registry.loadRoots([{ path: FIXTURE_DIR, source: 'user' }]);
+
+    // Step 1: Model receives user request "set up postgres database"
+    // Step 2: Model calls Skill tool with action:search
+    const searchResults = registry.searchSkills('postgres database setup', 5);
+    expect(searchResults.length).toBeGreaterThan(0);
+    expect(searchResults[0]!.description).toContain('postgres');
+
+    // Step 3: Model picks top result
+    const picked = searchResults[0]!;
+
+    // Step 4: Model calls Skill tool with action:load
+    const skill = registry.getSkill(picked.name);
+    expect(skill).toBeDefined();
+
+    // Step 5: renderSkillPrompt lazy-loads content
+    const rendered = registry.renderSkillPrompt(skill!, '');
+    // renderSkillPrompt returns raw content; the <kimi-skill-loaded> wrapper
+    // is added by skill-tool.ts execution path, not here
+    expect(rendered.length).toBeGreaterThan(0);
+    expect(rendered).toContain('postgres');
+    expect(rendered).toContain('Follow these steps');
+
+    console.log('\n✅ Full model flow simulation:');
+    console.log(`   1. User: "set up postgres database"`);
+    console.log(`   2. Skill action:search → ${searchResults.length} results`);
+    console.log(`   3. Model picks: ${picked.name} (score: ${picked.score})`);
+    console.log(`   4. Skill action:load → ${rendered.length} chars rendered`);
+    console.log(`   5. Content: "${rendered.slice(0, 60)}..."`);
+  });
+});
diff --git a/packages/agent-core/test/tools/skill-tool.test.ts b/packages/agent-core/test/tools/skill-tool.test.ts
index be9ae88f1..1e6f02d70 100644
--- a/packages/agent-core/test/tools/skill-tool.test.ts
+++ b/packages/agent-core/test/tools/skill-tool.test.ts
@@ -4,6 +4,10 @@ import type { Agent } from '../../src/agent';
 import type { SkillActivationOrigin } from '../../src/agent/context';
 import type { SkillRegistry as AgentSkillRegistry } from '../../src/agent/skill';
 import { SessionSkillRegistry, type SkillDefinition } from '../../src/skill';
+import {
+  compileToolArgsValidator,
+  validateToolArgs,
+} from '../../src/tools/args-validator';
 import {
   MAX_SKILL_QUERY_DEPTH,
   NestedSkillTooDeepError,
@@ -79,7 +83,7 @@ function skillTool(
   return new SkillTool(skillToolAgent(skills, methods), options);
 }
 
-function execute(tool: SkillTool, args: { skill: string; args?: string }) {
+function execute(tool: SkillTool, args: { skill?: string; args?: string; action?: 'load' | 'search'; query?: string; limit?: number }) {
   return executeTool(tool, {
     turnId: '0',
     toolCallId: 'call_skill',
@@ -99,9 +103,19 @@ describe('SkillTool metadata and schema', () => {
     });
     expect(SkillToolInputSchema.safeParse({ skill: 'commit' }).success).toBe(true);
     expect(SkillToolInputSchema.safeParse({ skill: 'commit', args: '-m fix' }).success).toBe(true);
-    expect(SkillToolInputSchema.safeParse({}).success).toBe(false);
+    // skill is optional — empty object is valid for search-only calls
+    expect(SkillToolInputSchema.safeParse({}).success).toBe(true);
+    expect(SkillToolInputSchema.safeParse({ action: 'search', query: 'test' }).success).toBe(true);
     expect(MAX_SKILL_QUERY_DEPTH).toBe(3);
   });
+
+  it('advertises a schema that validates search-only calls without a skill name', () => {
+    const tool = skillTool(registry());
+    const validator = compileToolArgsValidator(tool.parameters);
+
+    expect(validateToolArgs(validator, { action: 'search', query: 'e2e test' })).toBeNull();
+    expect(validateToolArgs(validator, { action: 'load', skill: 'commit' })).toBeNull();
+  });
 });
 
 describe('SkillTool execution', () => {
@@ -290,3 +304,57 @@ describe('SkillTool recursion guard', () => {
     await expect(execute(tool, { skill: 'loop' })).rejects.toBeInstanceOf(NestedSkillTooDeepError);
   });
 });
+
+describe('SkillTool search action', () => {
+  it('returns ranked search results', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(
+      registry([
+        skill('docker-expert', {}, 'Docker containerization guide'),
+        skill('react-ui', {}, 'React component patterns'),
+      ]),
+      methods,
+    );
+
+    const result = await execute(tool, { action: 'search', query: 'docker container' });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.output).toContain('docker-expert');
+    expect(result.output).toContain('score:');
+    expect(result.output).toContain('Call again with action:"load"');
+    expect(methods.recordSkillActivation).not.toHaveBeenCalled();
+    expect(methods.recordUserMessage).not.toHaveBeenCalled();
+  });
+
+  it('falls back to skill name as query when query is omitted', async () => {
+    const tool = skillTool(
+      registry([
+        skill('docker-expert', {}, 'Docker containerization guide'),
+        skill('react-ui', {}, 'React component patterns'),
+      ]),
+    );
+
+    const result = await execute(tool, { action: 'search', skill: 'react' });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.output).toContain('react-ui');
+  });
+
+  it('errors when search query is missing', async () => {
+    const tool = skillTool(registry());
+
+    const result = await execute(tool, { action: 'search' });
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('search query is required');
+  });
+
+  it('returns no-results message when nothing matches', async () => {
+    const tool = skillTool(registry([skill('alpha')]));
+
+    const result = await execute(tool, { action: 'search', query: 'zzzzzz' });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.output).toContain('No skills found');
+  });
+});