all-hands-cli 0.1.5 → 0.1.7

package/.allhands/flows/COMPOUNDING.md

@@ -67,8 +67,8 @@ Identify patterns that indicate harness improvement opportunities:
 ## Memory Extraction
 
 Per **Knowledge Compounding**, capture learnings as memories:
-- Run `ah memories search <relevant terms>` to check for existing similar memories before writing duplicates
-- Write to `docs/memories.md` (searchable via `ah memories search`)
+- Run `ah solutions search "<relevant terms>"` to check for existing similar memories before writing duplicates
+- Write to `docs/memories.md`
 - Format: `[Name] | [Domain] | [Source] | [Description]`
   - Domains: `planning`, `validation`, `implementation`, `harness-tooling`, `ideation`
   - Sources: `user-steering`, `agent-inferred`
@@ -113,7 +113,7 @@ For each documentable solution:
 ### Cross-Reference Solutions
 
 After all solutions are written, cross-reference related solutions:
-- Run `ah solutions list` then `ah solutions search` with terms from each new solution
+- Run `ah solutions search` with terms from each new solution to find related solutions
 - For solutions sharing components, tags, or thematic overlap: add "## Related" section with links
 - Update existing similar solutions with cross-reference back to new solutions
 

package/.allhands/flows/EMERGENT_PLANNING.md

@@ -17,7 +17,7 @@ Plan hypotheses as prompt files for executors to implement. Per **Quality Engine
 - Read `core_consolidation` from alignment doc frontmatter (default: `pending` if missing)
 - Read the workflow domain config at `WORKFLOW_DOMAIN_PATH` for `max_tangential_hypotheses`
 - Identify gaps between current state (completed work) and desired state (spec goals + success criteria)
-- Run `ah memories search "<hypothesis terms>"` for relevant prior insights
+- Run `ah solutions search "<hypothesis terms>"` for relevant prior insights
 
 ## Phase Determination
 

package/.allhands/flows/INITIATIVE_STEERING.md

@@ -34,7 +34,6 @@ Ground against current execution state — this is the core difference from spec
   - Compare completed work (prompt summaries) against spec goals
   - Identify gaps, risks, and drift between plan and reality
 - Run `ah solutions search "<steering context keywords>"` for relevant past solutions
-- Run `ah memories search "<steering context keywords>"` for relevant learnings
 
 ## Deep Grounding
 

package/.allhands/flows/PROMPT_TASK_EXECUTION.md

@@ -18,7 +18,6 @@ Execute prompt tasks with full context, validate thoroughly, and document your w
 - Only if additional context is needed (likely not needed):
   - Run `ah knowledge docs search <descriptive_query>` for codebase information as needed
   - Run `ah solutions search "<keywords>"` for relevant past solutions
-  - Run `ah memories search "<keywords>"` for relevant learnings and engineer preferences
 
 ## Implementation
 

package/.allhands/flows/SPEC_PLANNING.md

@@ -31,8 +31,7 @@ Transform the spec into executable prompts with domain-appropriate planning dept
 - Read the alignment doc for existing prompts that may impact planning (if exists)
 - Read codebase files referenced in spec for initial grounding
 - Ensure your branch is up to date with base branch
-- Search documented solutions with `ah solutions search "<keywords>"` for relevant past learnings
-- Search memories with `ah memories search "<keywords>"` for engineer preferences and prior spec insights
+- Run `ah solutions search "<keywords>"` for relevant past learnings and engineer preferences
 
 ## Idempotency Check
 

package/.allhands/flows/harness/WRITING_HARNESS_FLOWS.md

@@ -20,7 +20,7 @@ Guide agents through flow authoring with harness conventions. Per **Context is P
 ## Execution
 
 - Read `.allhands/principles.md` for first principle context
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/writing-flows.md` for flow authoring patterns
 - Author the flow using conventions: `<goal>`, `<inputs>`, `<outputs>`, `<constraints>`, action-verb bullets
 - Verify flow follows progressive disclosure — reference sub-flows rather than inlining complexity

package/.allhands/flows/harness/WRITING_HARNESS_KNOWLEDGE.md

@@ -20,7 +20,7 @@ Guide agents through knowledge compounding infrastructure — docs, solutions, m
 ## Execution
 
 - Read `.allhands/principles.md` for first principle context
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/knowledge-compounding.md` for schemas and compounding patterns
 - Create or update the knowledge artifact following type-specific conventions
 - Ensure proper indexing for discoverability via `ah knowledge docs search` or `ah solutions search`

package/.allhands/flows/harness/WRITING_HARNESS_ORCHESTRATION.md

@@ -20,7 +20,7 @@ Guide agents through orchestration layer changes — TUI lifecycle, event loop,
 ## Execution
 
 - Read `.allhands/principles.md` for first principle context
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/core-architecture.md` for architecture, schemas, and lifecycle patterns
 - Implement changes preserving architectural invariants (graceful degradation, semantic validation, in-memory state)
 - Validate with `ah validate agents` after profile modifications

package/.allhands/flows/harness/WRITING_HARNESS_SKILLS.md

@@ -20,7 +20,7 @@ Guide agents through skill creation and maintenance. Per **Context is Precious**
 ## Execution
 
 - Read `.allhands/principles.md` for first principle context
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/harness-skills.md` for skill schema, discovery mechanism, and conventions
 - Create or update the skill following hub-and-spoke pattern
 - Ensure glob coverage matches the skill's domain files

package/.allhands/flows/harness/WRITING_HARNESS_TOOLS.md

@@ -20,7 +20,7 @@ Guide agents through adding or modifying harness tools (CLI commands, hooks, MCP
 ## Execution
 
 - Read `.allhands/principles.md` for first principle context
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/tools-commands-mcp-hooks.md` for tool architecture and patterns
 - Implement the tool following auto-discovery conventions
 - Validate with `ah validate agents` if agent profiles are affected

package/.allhands/flows/harness/WRITING_HARNESS_VALIDATION_TOOLING.md

@@ -20,7 +20,7 @@ Guide agents through validation suite creation. Per **Agentic Validation Tooling
 ## Execution
 
 - Read `.allhands/principles.md` for first principle context
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/validation-tooling.md` for suite philosophy and crystallization patterns
 - Design the suite with both stochastic and deterministic sections
 - Validate suite existence threshold — ensure meaningful stochastic dimension exists

package/.allhands/flows/shared/CODEBASE_UNDERSTANDING.md

@@ -19,8 +19,7 @@ Choose the right tool for the query type:
 | **Great codebase navigation tool AND documented knowledge!!** | `ah knowledge docs search` | "How does X work?", "Why is Y designed this way?" |
 | **Find relevant codebase patterns when knowledge search is not enough** | `tldr semantic search` or grep | Known string, error message, literal pattern |
 | **Find symbol definition - usually from symbols given by knowledge search** | LSP | Class, function, type by name |
-| **Past solutions** | `ah solutions search` | Similar problem solved before |
-| **Past learnings** | `ah memories search` | Engineer preferences, validation gaps, prior insights |
+| **Past solutions + learnings** | `ah solutions search` | Similar problem solved before, engineer preferences, prior insights |
 | **Grep but better** | `ast-grep` | Known string, error message, literal pattern |
 
 ### Search Flow
@@ -58,7 +57,7 @@ Need codebase context?
     └─ Direct result? → relevant_files + [ref:...] blocks → LSP on symbols
 ├─ Know exact symbol? → LSP directly
 ├─ Know semantic idea? → tldr semantic search / grep
-├─ Suspect a similar problem faced before? → ah solutions search + ah memories search first
+├─ Suspect a similar problem faced before? → ah solutions search first
 └─ ast-grep if still struggling
 ```
 

package/.allhands/flows/shared/CREATE_VALIDATION_TOOLING_SPEC.md

@@ -21,7 +21,7 @@ Create a validation tooling spec for a new domain. Per **Prompt Files as Units o
 
 ## Domain Knowledge
 
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's `references/validation-tooling.md` for suite writing philosophy, crystallization lifecycle, evidence capture patterns, and tool validation guidance
 
 ## Research

package/.allhands/flows/shared/PLAN_DEEPENING.md

@@ -36,8 +36,8 @@ Spawn parallel subtasks for each research area:
 ### Skill Application
 
 Per **Frontier Models are Capable**, match skills to plan content:
-- Run `ah skills list` to discover available skills
-- For each domain in the plan, spawn subtask:
+- For each domain in the plan, run `ah skills search` to find applicable skills
+- For matched skills, spawn subtask:
   - Read matched skill's SKILL.md
   - Apply skill patterns to relevant prompts
   - Return best practices and gotchas
@@ -46,7 +46,6 @@ Per **Frontier Models are Capable**, match skills to plan content:
 
 Per **Knowledge Compounding**, check for relevant past solutions:
 - Run `ah solutions search "<domain keywords>"` for each technology area
-- Run `ah memories search "<domain keywords>"` for relevant learnings and engineer preferences
 - For high-scoring matches, extract:
   - Key insights that apply
   - Gotchas to avoid

package/.allhands/flows/shared/PROMPT_TASKS_CURATION.md

@@ -44,12 +44,10 @@ Create, edit, and maintain Prompt Task files - the atomic unit of work. Per **Pr
 
 Skills embed domain expertise into prompts - "how to do it right."
 
-Read `.allhands/flows/shared/SKILL_EXTRACTION.md` and:
-- Run `ah skills list` to discover available skills
-- Match skills to the prompt's domain (by globs and description)
-- Read matched skill files for patterns, best practices, guidelines
-- Extract relevant knowledge and embed in Tasks section
+Run `ah skills search` with the prompt's domain and files being touched:
+- Embed returned skill guidance in the prompt's Tasks section
 - Add matched skill file paths to `skills` frontmatter
+- Read skill reference files if deeper detail is needed
 
 Skills provide: code patterns, library preferences, common pitfalls, domain-specific best practices.
 

package/.allhands/flows/shared/WRITING_HARNESS_FLOWS.md

@@ -4,7 +4,7 @@ Flow authoring conventions for the All Hands harness. Per **Knowledge Compoundin
 
 ## Start Here
 
-- Run `ah skills list` to discover the `harness-maintenance` skill
+- Run `ah skills search` to discover the `harness-maintenance` skill
 - Read the skill's routing table — select `references/writing-flows.md` for flow authoring patterns
 - For execution, follow `.allhands/flows/harness/WRITING_HARNESS_FLOWS.md`
 

package/.allhands/flows/shared/jury/BEST_PRACTICES_REVIEW.md

@@ -15,7 +15,7 @@ Review implementation for domain best practices compliance. Per **Knowledge Comp
 </outputs>
 
 <constraints>
-- MUST extract skills using SKILL_EXTRACTION.md subtask
+- MUST extract skills using `ah skills search`
 - MUST search codebase knowledge for established patterns
 - MUST use research tools if no skill findings exist for the domain
 - MUST order issues by priority for fixing
@@ -29,9 +29,9 @@ Review implementation for domain best practices compliance. Per **Knowledge Comp
 
 ## Best Practices Extraction
 
-Spawn subtask to read `.allhands/flows/shared/SKILL_EXTRACTION.md`:
-- Provide the domain files as input
-- Extract patterns, preferences, and pitfalls for this domain
+Run `ah skills search` with the domain and relevant files:
+- Use returned guidance and skill references as review criteria
+- Read skill reference files if deeper detail is needed
 
 Search codebase knowledge:
 - Run `ah knowledge docs search "<domain> best practices"` for established patterns

package/.allhands/harness/src/cli.ts

@@ -28,6 +28,10 @@ async function main(): Promise<void> {
   await discoverAndRegister(program);
 
   await program.parseAsync();
+
+  // CLI subcommands may leave open handles (e.g. OpenCode SDK server sockets).
+  // TUI manages its own process.exit(), so this only affects subcommand runs.
+  process.exit(0);
 }
 
 main().catch((e) => {

package/.allhands/harness/src/commands/knowledge.ts

@@ -17,6 +17,7 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import {
   AgentRunner,
+  withDebugInfo,
   type AggregatorOutput,
   type SearchResult,
 } from "../lib/opencode/index.js";
@@ -121,13 +122,15 @@ class SearchCommand extends BaseCommand {
     cmd
       .argument("<query>", "Descriptive phrase (e.g. 'how to handle API authentication')")
       .option("--metadata-only", "Return only file paths and descriptions (no full content)")
-      .option("--no-aggregate", "Disable aggregation entirely");
+      .option("--no-aggregate", "Disable aggregation entirely")
+      .option("--debug", "Include agent debug metadata (model, timing, fallback) in output");
   }
 
   async execute(args: Record<string, unknown>): Promise<CommandResult> {
     const query = args.query as string;
     const metadataOnly = !!args.metadataOnly;
     const noAggregate = !!args.noAggregate;
+    const debug = !!args.debug;
 
     if (!query) {
       return this.error("validation_error", "query is required");
@@ -199,17 +202,17 @@ class SearchCommand extends BaseCommand {
 
       if (!agentResult.success) {
         // Fall back to raw results on aggregation failure
-        return this.success({
+        return this.success(withDebugInfo({
           index: this.indexName,
           query,
           results,
           result_count: results.length,
           aggregated: false,
           aggregation_error: agentResult.error,
-        });
+        }, agentResult, debug));
       }
 
-      return this.success({
+      return this.success(withDebugInfo({
         index: this.indexName,
         query,
         aggregated: true,
@@ -217,7 +220,7 @@ class SearchCommand extends BaseCommand {
         lsp_entry_points: agentResult.data!.lsp_entry_points,
         design_notes: agentResult.data!.design_notes,
         source_results: results.length,
-      });
+      }, agentResult, debug));
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       return this.error("search_error", message);

package/.allhands/harness/src/commands/skills.ts

@@ -1,10 +1,11 @@
 /**
  * Skills Command (Agent-Facing)
  *
- * Lists and discovers skills for domain expertise.
+ * Searches and discovers skills for domain expertise.
  * Agents use this to find relevant skills for their tasks.
  *
- * Usage: ah skills list
+ * Usage:
+ *   ah skills search <query> [--paths <paths...>] [--limit <n>] [--no-aggregate]
  */
 
 import { Command } from 'commander';
@@ -12,7 +13,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { parse as parseYaml } from 'yaml';
+import { minimatch } from 'minimatch';
 import { tracedAction } from '../lib/base-command.js';
+import { AgentRunner, withDebugInfo, type SkillSearchOutput } from '../lib/opencode/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -32,6 +35,31 @@ interface SkillEntry {
   file: string;
 }
 
+interface SkillMatch extends SkillEntry {
+  score: number;
+  matchedFields: string[];
+  pathMatch: boolean;
+}
+
+/** Scoring weights for keyword matching against skill fields. */
+const SCORE_WEIGHT = {
+  NAME: 3,
+  DESCRIPTION: 3,
+  GLOBS: 2,
+  PATH_BOOST: 4,
+} as const;
+
+// Load aggregator prompt from file
+const AGGREGATOR_PROMPT_PATH = join(__dirname, '../lib/opencode/prompts/skills-aggregator.md');
+
+const getAggregatorPrompt = (): string => {
+  return readFileSync(AGGREGATOR_PROMPT_PATH, 'utf-8');
+};
+
+const getProjectRoot = (): string => {
+  return process.env.PROJECT_ROOT || process.cwd();
+};
+
 /**
  * Extract frontmatter from markdown content
  */
@@ -50,6 +78,14 @@ function extractFrontmatter(content: string): Record<string, unknown> | null {
   }
 }
 
+/**
+ * Extract body content from markdown (everything after frontmatter)
+ */
+function extractBody(content: string): string {
+  const frontmatterRegex = /^---\n[\s\S]*?\n---\n?/;
+  return content.replace(frontmatterRegex, '').trim();
+}
+
 /**
  * Get the skills directory path
  * Path: harness/src/commands/ -> harness/src/ -> harness/ -> .allhands/ -> skills/
@@ -98,31 +134,278 @@ function listSkills(): SkillEntry[] {
   return skills;
 }
 
+/**
+ * Extract keywords from a search query.
+ * Handles quoted phrases and splits remaining words.
+ */
+function extractKeywords(query: string): string[] {
+  const keywords: string[] = [];
+  const quotedRegex = /"([^"]+)"/g;
+  let remaining = query;
+  let match;
+
+  while ((match = quotedRegex.exec(query)) !== null) {
+    keywords.push(match[1].toLowerCase());
+    remaining = remaining.replace(match[0], '');
+  }
+
+  const words = remaining
+    .split(/\s+/)
+    .map(w => w.toLowerCase().trim())
+    .filter(w => w.length > 1);
+
+  keywords.push(...words);
+  return keywords;
+}
+
+/**
+ * Score a skill against search keywords.
+ * Returns score and which fields matched.
+ */
+function scoreSkill(
+  entry: SkillEntry,
+  keywords: string[],
+): { score: number; matchedFields: string[] } {
+  let score = 0;
+  const matchedFields: string[] = [];
+  const nameLC = entry.name.toLowerCase();
+  const descLC = entry.description.toLowerCase();
+  const globsLC = entry.globs.join(' ').toLowerCase();
+
+  for (const kw of keywords) {
+    if (nameLC.includes(kw)) {
+      score += SCORE_WEIGHT.NAME;
+      if (!matchedFields.includes('name')) matchedFields.push('name');
+    }
+    if (descLC.includes(kw)) {
+      score += SCORE_WEIGHT.DESCRIPTION;
+      if (!matchedFields.includes('description')) matchedFields.push('description');
+    }
+    if (globsLC.includes(kw)) {
+      score += SCORE_WEIGHT.GLOBS;
+      if (!matchedFields.includes('globs')) matchedFields.push('globs');
+    }
+  }
+
+  return { score, matchedFields };
+}
+
+/**
+ * Check if a skill's globs match any of the provided file paths.
+ */
+function matchesPaths(skill: SkillEntry, paths: string[]): boolean {
+  for (const filePath of paths) {
+    for (const glob of skill.globs) {
+      if (minimatch(filePath, glob)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Search skills by keyword scoring with optional path boosting.
+ */
+function searchSkills(
+  query: string,
+  options: { paths?: string[]; limit?: number },
+): SkillMatch[] {
+  const { paths, limit = 10 } = options;
+  const allSkills = listSkills();
+  const keywords = extractKeywords(query);
+  const results: SkillMatch[] = [];
+
+  for (const skill of allSkills) {
+    const { score: keywordScore, matchedFields } = scoreSkill(skill, keywords);
+    const pathMatch = paths ? matchesPaths(skill, paths) : false;
+
+    let finalScore = keywordScore;
+
+    if (paths && pathMatch) {
+      finalScore = keywordScore > 0 ? keywordScore + SCORE_WEIGHT.PATH_BOOST : SCORE_WEIGHT.PATH_BOOST;
+    }
+
+    if (finalScore > 0) {
+      results.push({
+        ...skill,
+        score: finalScore,
+        matchedFields: pathMatch && matchedFields.length === 0
+          ? ['paths']
+          : pathMatch
+            ? [...matchedFields, 'paths']
+            : matchedFields,
+        pathMatch,
+      });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}
+
+/**
+ * Get the body content of a SKILL.md file (without frontmatter).
+ */
+function getSkillContent(entry: SkillEntry): string | null {
+  const dir = getSkillsDir();
+  const skillFile = join(dir, entry.name, 'SKILL.md');
+
+  if (!existsSync(skillFile)) return null;
+
+  const content = readFileSync(skillFile, 'utf-8');
+  return extractBody(content);
+}
+
+/**
+ * Get reference file paths for a skill (from references/ and docs/ subdirs).
+ */
+function getSkillReferenceFiles(entry: SkillEntry): string[] {
+  const dir = getSkillsDir();
+  const skillDir = join(dir, entry.name);
+  const refPaths: string[] = [];
+  const subdirs = ['references', 'docs'];
+
+  for (const subdir of subdirs) {
+    const subdirPath = join(skillDir, subdir);
+    if (!existsSync(subdirPath) || !statSync(subdirPath).isDirectory()) continue;
+
+    const files = readdirSync(subdirPath);
+    for (const file of files) {
+      if (file.endsWith('.md')) {
+        refPaths.push(`.allhands/skills/${entry.name}/${subdir}/${file}`);
+      }
+    }
+  }
+
+  return refPaths;
+}
+
+/**
+ * Run AI aggregation on skill matches to produce synthesized guidance.
+ * Returns a JSON-serializable result object.
+ */
+async function aggregateSkills(
+  query: string,
+  matches: SkillMatch[],
+  debug: boolean,
+): Promise<Record<string, unknown>> {
+  const skillsInput = matches.map(m => {
+    const content = getSkillContent(m);
+    const referenceFiles = getSkillReferenceFiles(m);
+    return {
+      name: m.name,
+      description: m.description,
+      globs: m.globs,
+      file: m.file,
+      content: content || '',
+      reference_files: referenceFiles,
+    };
+  });
+
+  const userMessage = JSON.stringify({ query, skills: skillsInput });
+  const projectRoot = getProjectRoot();
+  const runner = new AgentRunner(projectRoot);
+
+  try {
+    const agentResult = await runner.run<SkillSearchOutput>(
+      {
+        name: 'skills-aggregator',
+        systemPrompt: getAggregatorPrompt(),
+        timeoutMs: 60000,
+        steps: 5,
+      },
+      userMessage,
+    );
+
+    if (!agentResult.success) {
+      return withDebugInfo({
+        success: true,
+        query,
+        matches,
+        count: matches.length,
+        aggregated: false,
+        aggregation_error: agentResult.error,
+      }, agentResult, debug);
+    }
+
+    return withDebugInfo({
+      success: true,
+      query,
+      aggregated: true,
+      guidance: agentResult.data!.guidance,
+      relevant_skills: agentResult.data!.relevant_skills,
+      design_notes: agentResult.data!.design_notes,
+      source_matches: matches.length,
+    }, agentResult, debug);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      success: true,
+      query,
+      matches,
+      count: matches.length,
+      aggregated: false,
+      aggregation_error: message,
+    };
+  }
+}
+
 export function register(program: Command): void {
   const cmd = program
     .command('skills')
-    .description('Discover and list skills for domain expertise');
+    .description('Search and discover skills for domain expertise');
 
+  // Search subcommand
   cmd
-    .command('list')
-    .description('List all skills with their descriptions and glob patterns')
-    .option('--json', 'Output as JSON (default)')
-    .action(tracedAction('skills list', async () => {
-      const skills = listSkills();
+    .command('search')
+    .description('Search skills by query with optional path boosting and AI aggregation')
+    .argument('<query>', 'Descriptive search query (e.g. "how to write a flow")')
+    .option('--paths <paths...>', 'File paths to match against skill globs (boosts relevance)')
+    .option('--limit <n>', 'Maximum results', '10')
+    .option('--no-aggregate', 'Skip aggregation, return raw matches')
+    .option('--debug', 'Include agent debug metadata (model, timing, fallback) in output')
+    .action(tracedAction('skills search', async (query: string, _opts: Record<string, unknown>, command: Command) => {
+      const opts = command.opts();
+      const paths = opts.paths as string[] | undefined;
+      const limit = parseInt(opts.limit as string, 10) || 10;
+      const noAggregate = opts.aggregate === false;
+      const debug = !!opts.debug;
+
+      if (!query) {
+        console.log(JSON.stringify({
+          success: false,
+          error: 'validation_error: query is required',
+        }, null, 2));
+        return;
+      }
 
-      if (skills.length === 0) {
+      const matches = searchSkills(query, { paths, limit });
+
+      if (matches.length === 0) {
         console.log(JSON.stringify({
           success: true,
-          skills: [],
-          message: 'No skills found. Create skills in .allhands/skills/<name>/SKILL.md using `ah schema skill` for the file structure.',
+          query,
+          matches: [],
+          count: 0,
+          message: 'No skills matched the search query.',
         }, null, 2));
         return;
       }
 
-      console.log(JSON.stringify({
-        success: true,
-        skills,
-        count: skills.length,
-      }, null, 2));
+      // Return raw matches if aggregation disabled
+      if (noAggregate) {
+        console.log(JSON.stringify({
+          success: true,
+          query,
+          matches,
+          count: matches.length,
+          aggregated: false,
+        }, null, 2));
+        return;
+      }
+
+      const result = await aggregateSkills(query, matches, debug);
+      console.log(JSON.stringify(result, null, 2));
     }));
 }