opencode-agent-skills-md 1.0.0

package/packages/core/src/search.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Skill search and relevance ranking.
+ *
+ * Pure functions: no I/O, no host dependencies. Consumers pass in a list
+ * of `Skill` objects (already discovered by `core/discovery.ts`) and a
+ * free-text query plus an optional tag-keyword filter, and get back the
+ * same skills sorted by relevance.
+ *
+ * Scoring model (mirrors the design doc):
+ *
+ *   - name exact                = 100
+ *   - name prefix               = 90
+ *   - name fuzzy (sim > 0.4)    = 70 * sim
+ *   - trigger substring         = 60
+ *   - description ALL tokens    = 50  (bonus, added on top of per-token max+sum)
+ *   - description ANY token     = 30
+ *   - description fuzzy (best)  = 60 * sim (capped at 60)
+ *
+ * For multi-token queries, every token MUST contribute (AND across
+ * tokens). The final score is `max(per-token) + 0.1 * sum(per-token)`.
+ *
+ * `escapeRegex` lets callers treat the user query as a literal
+ * substring without leaking the regex engine into a crash on
+ * unbalanced parentheses, plus signs, etc.
+ */
+import type { Skill } from "./types";
+/**
+ * Escape every regex metacharacter in the input so the result is safe
+ * to embed in a `new RegExp(...)` call or treat as a literal substring.
+ *
+ * The escape set is intentionally defensive: it covers every character
+ * that the JS regex parser treats as syntax (`.*+?^${}()|[]\`) plus the
+ * hyphen, which is only a metacharacter inside a character class but is
+ * cheap to escape and avoids a footgun if the caller composes the
+ * result into a character class later.
+ */
+export declare function escapeRegex(input: string): string;
+/**
+ * Tokenize a free-text query into lowercase, non-empty tokens.
+ *
+ * Whitespace is the only separator. Empty tokens (from leading or
+ * trailing whitespace) are dropped so the caller never has to filter
+ * them out before scoring.
+ */
+export declare function tokenize(query: string): string[];
+/**
+ * Check whether a skill matches at least one of the supplied keywords
+ * against its `metadata.tags`. OR semantics: a single tag hit is enough
+ * to keep the skill in the result set. An empty keyword list is a no-op
+ * (every skill passes).
+ */
+export declare function keywordMatch(skill: Skill, keywords: string[]): boolean;
+/**
+ * Score a skill against a list of pre-tokenized, lowercase query
+ * tokens. Returns 0 when the skill has no chance of matching (used to
+ * drop it from the result). Positive scores compare higher = more
+ * relevant.
+ *
+ * The "description contains ALL tokens" tier (50) is applied as a
+ * per-token lift, not a flat bonus, so the ordering
+ *   name exact > name prefix > name fuzzy > trigger > desc-all > desc-any
+ * is preserved even after the `max + 0.1 * sum` multi-token formula.
+ *
+ * The `trigger` tier (60) is a flat per-token contribution: any token
+ * that appears as a case-insensitive substring of `skill.trigger` adds
+ * 60 to that token's contribution. Trigger is sandwiched between the
+ * name tiers (≥70) and the description tiers (≤50) so the invariant
+ *   name > trigger > description
+ * holds for single-token queries.
+ */
+export declare function scoreSkill(skill: Skill, tokens: string[]): number;
+/**
+ * Filter, score, and rank skills against a free-text query and an
+ * optional tag-keyword filter. The keyword filter applies first
+ * (it is the cheaper predicate and can only narrow the candidate
+ * set), then the query is tokenized and scored.
+ *
+ * Returns a new array sorted by score descending. Skills with a score
+ * of 0 are dropped. When the query is empty AND no keywords are
+ * supplied, the input list is returned unchanged (the caller can use
+ * the unranked discovery for browsing).
+ */
+export declare function searchSkills(skills: Skill[], query: string, keywords?: string[]): Skill[];

package/packages/core/src/search.ts

@@ -0,0 +1,188 @@
+/**
+ * Skill search and relevance ranking.
+ *
+ * Pure functions: no I/O, no host dependencies. Consumers pass in a list
+ * of `Skill` objects (already discovered by `core/discovery.ts`) and a
+ * free-text query plus an optional tag-keyword filter, and get back the
+ * same skills sorted by relevance.
+ *
+ * Scoring model (mirrors the design doc):
+ *
+ *   - name exact                = 100
+ *   - name prefix               = 90
+ *   - name fuzzy (sim > 0.4)    = 70 * sim
+ *   - trigger substring         = 60
+ *   - description ALL tokens    = 50  (bonus, added on top of per-token max+sum)
+ *   - description ANY token     = 30
+ *   - description fuzzy (best)  = 60 * sim (capped at 60)
+ *
+ * For multi-token queries, every token MUST contribute (AND across
+ * tokens). The final score is `max(per-token) + 0.1 * sum(per-token)`.
+ *
+ * `escapeRegex` lets callers treat the user query as a literal
+ * substring without leaking the regex engine into a crash on
+ * unbalanced parentheses, plus signs, etc.
+ */
+
+import type { Skill } from "./types";
+import { levenshtein } from "./match";
+
+/**
+ * Escape every regex metacharacter in the input so the result is safe
+ * to embed in a `new RegExp(...)` call or treat as a literal substring.
+ *
+ * The escape set is intentionally defensive: it covers every character
+ * that the JS regex parser treats as syntax (`.*+?^${}()|[]\`) plus the
+ * hyphen, which is only a metacharacter inside a character class but is
+ * cheap to escape and avoids a footgun if the caller composes the
+ * result into a character class later.
+ */
+export const escapeRegex = (input: string): string => {
+  return input.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+};
+
+/**
+ * Tokenize a free-text query into lowercase, non-empty tokens.
+ *
+ * Whitespace is the only separator. Empty tokens (from leading or
+ * trailing whitespace) are dropped so the caller never has to filter
+ * them out before scoring.
+ */
+export const tokenize = (query: string): string[] => {
+  return query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((t) => t.length > 0);
+};
+
+/**
+ * Check whether a skill matches at least one of the supplied keywords
+ * against its `metadata.tags`. OR semantics: a single tag hit is enough
+ * to keep the skill in the result set. An empty keyword list is a no-op
+ * (every skill passes).
+ */
+export const keywordMatch = (skill: Skill, keywords: string[]): boolean => {
+  if (keywords.length === 0) return true;
+  const tags = skill.tags ?? [];
+  return keywords.some((kw) => tags.includes(kw));
+};
+
+/** Compute a Levenshtein-derived similarity in the 0..1 range. */
+const similarity = (a: string, b: string): number => {
+  if (a.length === 0 && b.length === 0) return 1;
+  return 1 - levenshtein(a, b) / Math.max(a.length, b.length);
+};
+
+/** Best description-token fuzzy similarity for a single query token. */
+const bestDescriptionTokenSim = (descLower: string, token: string): number => {
+  let best = 0;
+  for (const dt of descLower.split(/\s+/)) {
+    if (dt.length === 0) continue;
+    const sim = similarity(dt, token);
+    if (sim > best) best = sim;
+  }
+  return best;
+};
+
+/**
+ * Score a skill against a list of pre-tokenized, lowercase query
+ * tokens. Returns 0 when the skill has no chance of matching (used to
+ * drop it from the result). Positive scores compare higher = more
+ * relevant.
+ *
+ * The "description contains ALL tokens" tier (50) is applied as a
+ * per-token lift, not a flat bonus, so the ordering
+ *   name exact > name prefix > name fuzzy > trigger > desc-all > desc-any
+ * is preserved even after the `max + 0.1 * sum` multi-token formula.
+ *
+ * The `trigger` tier (60) is a flat per-token contribution: any token
+ * that appears as a case-insensitive substring of `skill.trigger` adds
+ * 60 to that token's contribution. Trigger is sandwiched between the
+ * name tiers (≥70) and the description tiers (≤50) so the invariant
+ *   name > trigger > description
+ * holds for single-token queries.
+ */
+export const scoreSkill = (skill: Skill, tokens: string[]): number => {
+  if (tokens.length === 0) return 0;
+  const name = skill.name.toLowerCase();
+  const desc = skill.description.toLowerCase();
+  const trigger = skill.trigger?.toLowerCase() ?? "";
+
+  // When every token appears in the description, each per-token
+  // description contribution is lifted from 30 (ANY) to 50 (ALL).
+  const descTier = tokens.every((t) => desc.includes(t)) ? 50 : 30;
+
+  // Per-token contribution. We pick the strongest tier for each token,
+  // then require every token to contribute (AND across tokens). The
+  // first token that contributes nothing forces the whole score to 0.
+  const perToken: number[] = [];
+  for (const token of tokens) {
+    let s = 0;
+
+    if (name === token) {
+      s = Math.max(s, 100);
+    } else if (name.startsWith(token)) {
+      s = Math.max(s, 90);
+    } else {
+      const nameSim = similarity(name, token);
+      if (nameSim > 0.4) s = Math.max(s, 70 * nameSim);
+    }
+
+    if (trigger.length > 0 && trigger.includes(token)) {
+      s = Math.max(s, 60);
+    }
+
+    if (desc.includes(token)) {
+      s = Math.max(s, descTier);
+    } else {
+      const descSim = bestDescriptionTokenSim(desc, token);
+      if (descSim > 0.4) s = Math.max(s, Math.min(60, 60 * descSim));
+    }
+
+    if (s === 0) return 0; // AND: this token cannot be satisfied.
+    perToken.push(s);
+  }
+
+  const max = Math.max(...perToken);
+  const sum = perToken.reduce((a, b) => a + b, 0);
+  return max + 0.1 * sum;
+};
+
+/**
+ * Filter, score, and rank skills against a free-text query and an
+ * optional tag-keyword filter. The keyword filter applies first
+ * (it is the cheaper predicate and can only narrow the candidate
+ * set), then the query is tokenized and scored.
+ *
+ * Returns a new array sorted by score descending. Skills with a score
+ * of 0 are dropped. When the query is empty AND no keywords are
+ * supplied, the input list is returned unchanged (the caller can use
+ * the unranked discovery for browsing).
+ */
+export const searchSkills = (
+  skills: Skill[],
+  query: string,
+  keywords?: string[]
+): Skill[] => {
+  let candidates: Skill[] = skills;
+
+  if (keywords && keywords.length > 0) {
+    candidates = candidates.filter((s) => keywordMatch(s, keywords!));
+  }
+
+  if (!query || query.trim() === "") {
+    return candidates;
+  }
+
+  const tokens = tokenize(query);
+  if (tokens.length === 0) {
+    return candidates;
+  }
+
+  const scored = candidates
+    .map((skill) => ({ skill, score: scoreSkill(skill, tokens) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  return scored.map(({ skill }) => skill);
+};

package/packages/core/src/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure types for the skills core engine.
+ *
+ * The core has zero runtime dependency on any host SDK. Host-specific types
+ * (the OpenCode client, session context, etc.) live in the host adapter and
+ * are re-exported by the consumer entrypoints.
+ *
+ * Boundary contracts `SkillHostClient` and `SkillHostSession` declare the
+ * surface the core expects from any AI harness host. They are forward-looking
+ * for PR2 (the OpenCode adapter) and are not yet consumed by core code.
+ */
+/**
+ * Skill label indicating the source/location of a skill.
+ * - project: .opencode/skills/ in project directory
+ * - user: ~/.config/opencode/skills/
+ * - claude-project: .claude/skills/ in project directory
+ * - claude-user: ~/.claude/skills/
+ */
+export type SkillLabel = "project" | "user" | "claude-project" | "claude-user";
+/**
+ * Result from finding a file in a directory.
+ */
+export interface FileDiscoveryResult {
+    filePath: string;
+    relativePath: string;
+}
+/**
+ * Script metadata with both relative and absolute paths.
+ */
+export interface Script {
+    relativePath: string;
+    absolutePath: string;
+}
+/**
+ * Complete metadata for a discovered skill.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    /**
+     * Free-form trigger phrase(s) parsed from the `trigger` frontmatter key.
+     * Surfaced in targeted outputs (matched-skill injection, `get_available_skills`)
+     * so the model knows which user phrases should activate the skill. Absent
+     * when the frontmatter has no `trigger` key.
+     */
+    trigger?: string;
+    path: string;
+    relativePath: string;
+    namespace?: string;
+    label: SkillLabel;
+    scripts: Script[];
+    template: string;
+    /**
+     * Free-form tags parsed from `metadata.tags` in the skill frontmatter.
+     * Defaults to an empty array when the skill has no `metadata` block or
+     * the block has no `tags` key. Consumers (e.g. the search layer) use
+     * this list to filter skills by user-supplied keywords.
+     */
+    tags: string[];
+}
+/**
+ * Skill summary for preflight evaluation.
+ */
+export interface SkillSummary {
+    name: string;
+    description: string;
+    /**
+     * Optional trigger phrase(s) parsed from the `trigger` frontmatter key.
+     * Mirrors `Skill.trigger` so summaries carry the same discovery metadata.
+     */
+    trigger?: string;
+}
+/** Discovery result with label attached. */
+export type LabeledDiscoveryResult = FileDiscoveryResult & {
+    label: SkillLabel;
+};
+/** Configuration for a skill discovery path. */
+export interface DiscoveryPath {
+    path: string;
+    label: SkillLabel;
+    maxDepth: number;
+}

package/packages/core/src/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure types for the skills core engine.
+ *
+ * The core has zero runtime dependency on any host SDK. Host-specific types
+ * (the OpenCode client, etc.) live in the host adapter and are re-exported
+ * by the consumer entrypoints.
+ *
+ * Boundary contracts `SkillHostClient` and `SkillHostSession` (and the
+ * minimal `SkillHostContext` they reference) declare the surface the core
+ * expects from any AI harness host. The concrete OpenCode implementation
+ * lives in the plugin package; other harnesses implement the same contracts.
+ */
+
+/**
+ * Skill label indicating the source/location of a skill.
+ * - project: .opencode/skills/ in project directory
+ * - user: ~/.config/opencode/skills/
+ * - claude-project: .claude/skills/ in project directory
+ * - claude-user: ~/.claude/skills/
+ */
+export type SkillLabel = "project" | "user" | "claude-project" | "claude-user";
+
+/**
+ * Result from finding a file in a directory.
+ */
+export interface FileDiscoveryResult {
+  filePath: string;
+  relativePath: string;
+}
+
+/**
+ * Script metadata with both relative and absolute paths.
+ */
+export interface Script {
+  relativePath: string;
+  absolutePath: string;
+}
+
+/**
+ * Complete metadata for a discovered skill.
+ */
+export interface Skill {
+  name: string;
+  description: string;
+  /**
+   * Free-form trigger phrase(s) parsed from the `trigger` frontmatter key.
+   * Surfaced in targeted outputs (matched-skill injection, `get_available_skills`)
+   * so the model knows which user phrases should activate the skill. Absent
+   * when the frontmatter has no `trigger` key.
+   */
+  trigger?: string;
+  path: string;
+  relativePath: string;
+  namespace?: string;
+  label: SkillLabel;
+  scripts: Script[];
+  template: string;
+  /**
+   * Free-form tags parsed from `metadata.tags` in the skill frontmatter.
+   * Defaults to an empty array when the skill has no `metadata` block or
+   * the block has no `tags` key. Consumers (e.g. the search layer) use
+   * this list to filter skills by user-supplied keywords.
+   */
+  tags: string[];
+}
+
+/**
+ * Skill summary for preflight evaluation.
+ */
+export interface SkillSummary {
+  name: string;
+  description: string;
+  /**
+   * Optional trigger phrase(s) parsed from the `trigger` frontmatter key.
+   * Mirrors `Skill.trigger` so summaries carry the same discovery metadata.
+   */
+  trigger?: string;
+}
+
+/** Discovery result with label attached. */
+export type LabeledDiscoveryResult = FileDiscoveryResult & { label: SkillLabel };
+
+/** Configuration for a skill discovery path. */
+export interface DiscoveryPath {
+  path: string;
+  label: SkillLabel;
+  maxDepth: number;
+}
+
+/**
+ * Minimal per-call context the host carries alongside an injected message.
+ *
+ * The core never needs more than the model + agent hint that the host can
+ * resolve from a session. Declaring the shape here (instead of in the
+ * adapter) keeps the boundary contract self-contained: the plugin's
+ * OpenCode implementation supplies the values; future harnesses do the
+ * same without changing core.
+ */
+export interface SkillHostContext {
+  model?: { providerID: string; modelID: string };
+  agent?: string;
+}
+
+/**
+ * Bounded client surface the core expects from any AI harness host.
+ *
+ * The interface is intentionally structural — a host adapter may add more
+ * methods, but it MUST provide these four to satisfy the boundary. The
+ * concrete OpenCode implementation (`createOpencodeSkillHost` in the plugin
+ * package) supplies them over the OpenCode SDK client plus `node:fs`.
+ *
+ *   - `injectContent`        push a synthetic message into a session
+ *   - `getSessionContext`    resolve model/agent hint for a session id
+ *   - `readFile` / `readdir` bounded filesystem access for skill loading
+ */
+export interface SkillHostClient {
+  injectContent(sessionID: string, text: string, context?: SkillHostContext): Promise<void>;
+  getSessionContext(sessionID: string): Promise<SkillHostContext | undefined>;
+  readFile(path: string): Promise<string>;
+  readdir(path: string): Promise<string[]>;
+}
+
+/**
+ * Host-side session handle. The core only needs to carry the session id
+ * through calls back into the host (e.g. when injecting matched-skill
+ * content). Hosts are free to attach additional state internally; the
+ * boundary contract here is the minimum the core relies on.
+ */
+export interface SkillHostSession {
+  id: string;
+}

package/packages/core/src/walk.ts

@@ -0,0 +1,109 @@
+/**
+ * Internal shared directory walker.
+ *
+ * Walks `baseDir` recursively up to `maxDepth` and invokes `visitor` for each
+ * non-skipped entry. The walker owns the traversal rules shared by skill
+ * discovery (`findSkillsRecursive`) and script enumeration (`findScripts`):
+ *
+ *   - hidden directories (names starting with `.`) are skipped
+ *   - `node_modules` and `.git` are skipped unconditionally
+ *   - per-entry errors (read, stat, or visitor throw) are isolated so a
+ *     single broken symlink or throwing visitor does not abort the walk
+ *
+ * Callers that need extra skip sets (e.g. `__pycache__`, `.venv` for the
+ * scripts layer) pass them via {@link WalkOptions.skipDirs}. The walker does
+ * NOT re-export its skip rules — each caller decides what extra paths are
+ * not its business to enter.
+ *
+ * The walker is internal to the core package: it is intentionally NOT
+ * re-exported from `packages/core/src/index.ts`. Callers import it
+ * directly from `./walk`.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { Dirent } from "node:fs";
+
+/** Directories the walker skips on every invocation, regardless of caller. */
+const ALWAYS_SKIP = new Set(["node_modules", ".git"]);
+
+/**
+ * Optional walker configuration.
+ *
+ * Kept narrow on purpose: only fields both callers need belong here.
+ * Anything caller-specific (e.g. script executable-bit filter) lives in
+ * the visitor, not in the walker.
+ */
+export interface WalkOptions {
+  /**
+   * Extra directory names the walker should skip in addition to the
+   * unconditional `node_modules` / `.git` and the hidden-dir rule.
+   * Use this for caller-specific skip sets such as Python cache dirs
+   * or virtualenvs in the scripts layer.
+   */
+  skipDirs?: ReadonlySet<string>;
+}
+
+/**
+ * Walk `baseDir` recursively, invoking `visitor` for each non-skipped entry.
+ *
+ * The visitor is called depth-first with the entry's `parentPath` already
+ * populated (Node 20.12+), so callers can build absolute paths via
+ * `path.join(entry.parentPath, entry.name)` without restating the parent.
+ *
+ * `currentDepth` is the depth of the directory containing the entry:
+ * `0` for entries inside `baseDir`, `1` for entries inside its subdirs,
+ * and so on. Entries beyond `maxDepth` are never visited.
+ *
+ * The visitor may be sync or async; the walker awaits it so any state
+ * the visitor records (e.g. "skip this subtree") is visible to the
+ * subsequent recursive step.
+ *
+ * A missing or unreadable `baseDir` is not an error: the walker simply
+ * yields nothing. Per-entry failures (read, stat, or a throwing visitor)
+ * are likewise isolated to the offending entry.
+ */
+export const walkDir = async (
+  baseDir: string,
+  maxDepth: number,
+  visitor: (entry: Dirent, currentDepth: number) => void | Promise<void>,
+  options: WalkOptions = {}
+): Promise<void> => {
+  const skipDirs = options.skipDirs;
+  await walk(baseDir, 0, maxDepth, visitor, skipDirs);
+};
+
+const walk = async (
+  dir: string,
+  depth: number,
+  maxDepth: number,
+  visitor: (entry: Dirent, currentDepth: number) => void | Promise<void>,
+  skipDirs: ReadonlySet<string> | undefined
+): Promise<void> => {
+  if (depth > maxDepth) return;
+
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    // baseDir missing or unreadable: stay graceful, the walker is a utility.
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (ALWAYS_SKIP.has(entry.name)) continue;
+    if (skipDirs?.has(entry.name)) continue;
+
+    try {
+      await visitor(entry, depth);
+    } catch {
+      // Per-entry error isolation: a throwing visitor must not abort the walk.
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      await walk(path.join(dir, entry.name), depth + 1, maxDepth, visitor, skipDirs);
+    }
+  }
+};