opencode-agent-skills-md 1.0.0 → 1.1.0

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/tasks.md

@@ -1,65 +0,0 @@
-# Tasks: Fix Skill-Loading Regression
-
-## Review Workload Forecast
-
-| Field | Value |
-|-------|-------|
-| Estimated changed lines | 180-260 |
-| 400-line budget risk | Medium |
-| Chained PRs recommended | Yes |
-| Suggested split | PR 1 → PR 2 → PR 3 (optional) |
-| Delivery strategy | force-chained |
-| Chain strategy | stacked-to-main |
-
-Decision needed before apply: No
-Chained PRs recommended: Yes
-Chain strategy: stacked-to-main
-400-line budget risk: Medium
-
-### Suggested Work Units
-
-| Unit | Goal | Likely PR | Notes |
-|------|------|-----------|-------|
-| 1 | Restore callback seam + session dedupe | PR 1 | `src/opencode/*`; tests first |
-| 2 | Restore baseline discovery sources | PR 2 | `src/core/discovery.ts`; stack after PR 1 |
-| 3 | Cleanup only if scope stays tight | PR 3 | Optional polish + final verification |
-
-## Phase 1: PR 1 — Callback wiring
-
-- [x] 1.1 RED — Extend `tests/opencode/plugin.test.ts` and `tests/integration/plugin.test.ts` to fail when `use_skill` loads once but does not update loaded-session state or suppress duplicate re-injection; commit `test: add skill loading callback regression coverage`.
-- [x] 1.2 GREEN — Update `src/opencode/tools.ts` and `src/opencode/plugin.ts` to thread optional `onSkillLoaded` through `createSkillTools()` → `UseSkill()` and restore `loadedSkillsPerSession` updates; commit `fix: restore use-skill callback wiring`.
-- [x] 1.3 REFACTOR — Keep the callback seam optional, trim duplicated plugin-test setup, and rerun `node --import tsx --test tests/opencode/plugin.test.ts tests/integration/plugin.test.ts`; commit `refactor: preserve optional skill callback seam`.
-
-## Phase 2: PR 2 — Discovery breadth
-
-- [x] 2.1 RED — Extend `tests/integration/skill-discovery.test.ts` with baseline-coverage cases for `.opencode/skills`, `.claude/skills`, `~/.config/opencode/skills`, `~/.claude/skills`, plus the partial-trigger regression from spec R5; commit `test: add discovery breadth regression coverage`.
-- [x] 2.2 GREEN — Modify `src/core/discovery.ts` to restore the pre-refactor source set from `c2d8e74` while preserving first-match-wins and duplicate warnings; commit `fix: restore baseline skill discovery sources`.
-- [x] 2.3 REFACTOR — Normalize any helper/constants in `src/core/discovery.ts`, keep search/host boundaries unchanged, and rerun `node --import tsx --test tests/integration/skill-discovery.test.ts`; commit `refactor: clean up discovery source helpers`.
-
-## Phase 3: PR 3 — Optional cleanup / verification
-
-- [x] 3.1 RED/GREEN — Coverage gap check: PR 1 + PR 2 cover all spec R3/R5 scenarios. No additional regression needed; skip the commit.
-- [x] 3.2 REFACTOR — Code is already minimal (OnSkillLoaded type, inlined 4-line callback, DEFAULT_DISCOVERY_MAX_DEPTH constant). No behavior-neutral cleanup needed; skip the commit.
-- [x] 3.3 VERIFY — Run `pnpm run typecheck` (clean) and the full `pnpm test` suite (102 tests, 0 fail); commit `chore: verify skill loading regression fix`.
-
-## Final Commit Stack
-
-```
-d2c3584 test: correct dedupe assertion to allow other matches
-c1f5b27 chore: verify skill loading regression fix
-8c7de19 refactor: clean up discovery source helpers
-7e4293e fix: restore baseline skill discovery sources
-b764c15 test: add discovery breadth regression coverage
-9e975ab refactor: preserve optional skill callback seam
-fd4ab41 fix: restore use-skill callback wiring
-c64d4e7 test: add skill loading callback regression coverage
-01c4b46 chore(sdd): add fix-skill-loading-regression change artifacts
-```
-
-## Verification
-
-- `pnpm run typecheck` — clean
-- `node --import tsx --test src/utils.test.ts tests/core/*.test.ts tests/opencode/plugin.test.ts tests/integration/plugin.test.ts tests/integration/skill-discovery.test.ts tests/e2e/*.test.ts` — 89 pass / 0 fail
-- `pnpm test` (unit + core + opencode + integration + e2e) — 102 pass / 0 fail
-- All spec R3 scenarios covered: callback fires, dedupe, missing-callback
-- All spec R5 scenarios covered: priority + first-match-wins, baseline match, partial-trigger

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/verify-report.md

@@ -1,165 +0,0 @@
-## Verification Report
-
-**Change**: fix-skill-loading-regression
-**Version**: delta for core-decoupling (R3, R5)
-**Mode**: Strict TDD
-
----
-
-### Completeness
-| Metric | Value |
-|--------|-------|
-| Tasks total | 9 |
-| Tasks complete | 9 |
-| Tasks incomplete | 0 |
-
----
-
-### Build & Tests Execution
-**Build**: ✅ Passed
-```text
-$ CI=true pnpm run typecheck
-$ tsc --noEmit
-(no errors, silent)
-```
-
-**Tests**: ✅ 102 passed / 0 failed / 0 skipped
-```text
-unit:      42 pass (src/*.test.ts)
-core:      20 pass (tests/core/*.test.ts)
-opencode:  22 pass (tests/opencode/*.test.ts)   ← 3 new regression tests
-integration: 17 pass (tests/integration/*.test.ts) ← 2 new regression tests
-e2e:        1 pass (tests/e2e/*.test.ts)
-Total:   102 pass / 0 fail
-```
-
-**Coverage**: ➖ Not available (no coverage tool in project capabilities)
-
----
-
-### Spec Compliance Matrix
-
-#### R3 — Backward-Compatible Root Export
-
-| Scenario | Test | Result |
-|----------|------|--------|
-| Root export still loads the OpenCode plugin with four tool names | `tests/integration/startup-smoke.test.ts` (existing) | ✅ COMPLIANT |
-| use_skill fires the onSkillLoaded callback | `tests/opencode/plugin.test.ts` > "createSkillTools forwards onSkillLoaded so UseSkill invokes it (R3)" | ✅ COMPLIANT |
-| use_skill does not re-inject the same skill in one session | `tests/opencode/plugin.test.ts` > "plugin updates loadedSkillsPerSession so a repeat chat.message does not re-inject (R3 dedupe)" | ✅ COMPLIANT |
-| missing callback does not break the load | `tests/opencode/plugin.test.ts` > "use_skill still loads when no callback is registered (R3 missing-callback)" | ✅ COMPLIANT |
-
-#### R5 — Discovery Semantics Preservation
-
-| Scenario | Test | Result |
-|----------|------|--------|
-| Discovery priority and first-match-wins are preserved | `tests/integration/skill-discovery.test.ts` > "discoverAllSkills surfaces skills from all four priority locations" + "first-match-wins: project skill shadows the same-named user skill" | ✅ COMPLIANT |
-| discoverAllSkills matches the pre-refactor skill set | `tests/integration/skill-discovery.test.ts` > "discoverAllSkills surfaces skills from all four priority locations" | ✅ COMPLIANT |
-| Literal-token search does not drop the pre-refactor skill set | `tests/integration/skill-discovery.test.ts` > "a skill whose trigger tokens are partial substrings of the query still appears" | ✅ COMPLIANT |
-
-**Compliance summary**: 7/7 scenarios compliant
-
----
-
-### Correctness (Static Evidence)
-
-| Requirement | Status | Evidence |
-|------------|--------|---------|
-| R3 — onSkillLoaded threading through createSkillTools | ✅ Implemented | `src/opencode/tools.ts:79` — optional `onSkillLoaded?` 4th param; `src/opencode/tools.ts:316` — `onSkillLoaded?.()` called after injectContent |
-| R3 — loadedSkillsPerSession updated by callback | ✅ Implemented | `src/opencode/plugin.ts:120-122` — inline callback adds to session set |
-| R3 — dedupe via loadedSkillsPerSession | ✅ Implemented | `src/opencode/plugin.ts:187-188` — filter: `!loadedSkills.has(s.name)` |
-| R3 — missing callback is safe (optional) | ✅ Implemented | `onSkillLoaded?.()` uses optional chaining; no-op when undefined |
-| R5 — four-location priority restored | ✅ Implemented | `src/core/discovery.ts:125-132` — `getDefaultOpencodeRoots` returns all four roots |
-| R5 — first-match-wins preserved | ✅ Implemented | `src/core/discovery.ts:176-179` — duplicate handling calls `onDuplicate` but does not store |
-| R5 — DEFAULT_DISCOVERY_MAX_DEPTH = 3 | ✅ Implemented | `src/core/discovery.ts:113` constant; `src/core/discovery.ts:127-130` used in all four roots |
-| R5 — partial-trigger regression covered | ✅ Implemented | `tests/integration/skill-discovery.test.ts:277-314` — dynamically creates fixture skill and asserts it is surfaced |
-
----
-
-### Coherence (Design)
-
-| Decision | Followed? | Notes |
-|----------|-----------|-------|
-| Thread `onSkillLoaded` through `createSkillTools` → `UseSkill` | ✅ Yes | Signature change minimal (optional 4th arg); no behavioral change to other three tools |
-| Restore discovery breadth in `core/discovery.ts` | ✅ Yes | `getDefaultOpencodeRoots` widened to four locations; no changes to search/ranking/validation |
-| Keep core/host split intact | ✅ Yes | `src/core/` has zero references to `@opencode-ai/plugin`; host adapter only in `src/opencode/` |
-| Keep search engine, tag filtering, trigger-aware ranking, Zod parsing, path-safety | ✅ Yes | All preserved; `DEFAULT_DISCOVERY_MAX_DEPTH` constant extracted |
-| `getDefaultOpencodeRoots` remains canonical discovery-source definition | ✅ Yes | Returns `DiscoveryPath[]`; no host-specific knowledge moved to core modules |
-
----
-
-### TDD Compliance
-
-| Check | Result | Details |
-|-------|--------|---------|
-| TDD Evidence reported | ✅ | Found in `apply-progress.md` — "TDD Cycle Evidence" table with all rows |
-| All tasks have tests | ✅ | 9/9 tasks have test files or production commits |
-| RED confirmed (tests exist) | ✅ | 5 test files written/modified: `tests/opencode/plugin.test.ts`, `tests/integration/plugin.test.ts`, `tests/integration/skill-discovery.test.ts` |
-| GREEN confirmed (tests pass) | ✅ | All 102 tests pass on execution |
-| Triangulation adequate | ✅ | R3 has 3 test cases; R5 has 3 test cases (per spec scenarios) |
-| Safety Net for modified files | ✅ | Pre-existing tests (42 unit + 20 core + 22 opencode + 17 integration + 1 e2e = 102) ran before each PR |
-| TDD cycle completeness | ✅ | RED → GREEN → REFACTOR sequence documented per task |
-
-**TDD Compliance**: 7/7 checks passed
-
----
-
-### Test Layer Distribution
-
-| Layer | Tests | Files | Notes |
-|-------|-------|-------|-------|
-| Unit | 22 | 1 | `tests/opencode/plugin.test.ts` — matchSkillsByKeyword, formatMatchedSkillsInjection, callback wiring |
-| Integration | 17 | 2 | `tests/integration/plugin.test.ts` (plugin integration + keywords), `tests/integration/skill-discovery.test.ts` (discovery breadth + normalization) |
-| E2E | 1 | 1 | `tests/e2e/startup-smoke.test.ts` |
-| **Total** | **102** | **~12** | Full suite green |
-
----
-
-### Changed File Coverage
-
-| File | Lines (Δ) | Test Count | Coverage |
-|------|-----------|------------|----------|
-| `src/opencode/tools.ts` | +18/-3 | 3 regression tests | ⚠️ Low (no per-file coverage tool) |
-| `src/opencode/plugin.ts` | +7/-6 | 2 regression tests | ⚠️ Low (no per-file coverage tool) |
-| `src/core/discovery.ts` | +8/-5 | 4 regression tests | ⚠️ Low (no per-file coverage tool) |
-
-**Average changed file coverage**: ➖ Not available (no coverage tool detected)
-
----
-
-### Assertion Quality
-
-| File | Line | Assertion | Issue | Severity |
-|------|------|-----------|-------|----------|
-| — | — | — | — | — |
-
-**Assertion quality**: ✅ All assertions verify real behavior (no tautologies, no ghost loops, no smoke-only tests)
-
----
-
-### Issues Found
-
-**CRITICAL**: None
-**WARNING**: None
-**SUGGESTION**: None
-
----
-
-### Notable Observations
-
-1. **Dedupe assertion nuance**: The dedupe tests correctly assert that the *loaded* skill is *filtered out* of `<skill-evaluation-required>` injections — not that zero injections fire (other skills may match the same query tokens). This is the correct regression target per the apply-progress discovery log.
-
-2. **maxDepth deviation from c2d8e74 baseline**: Pre-refactor `c2d8e74` used `maxDepth: 1` for Claude-side roots; commit `12de52a` widened to 3 deliberately. The JSDoc in `discovery.ts` now documents this intentionally and the regression net locks `maxDepth: 3` in place.
-
-3. **Plugin/marketplace discovery out of scope**: The `c2d8e74` baseline also surfaced `~/.claude/plugins/cache/` and `~/.claude/plugins/marketplaces/`. The proposal correctly scoped this fix to the four standard locations only.
-
-4. **Callback already existed in UseSkill**: `UseSkill` already accepted `onSkillLoaded?` before the fix. `createSkillTools` simply never accepted or forwarded it. The fix is a minimal 2-line production code change.
-
----
-
-### Verdict
-
-**PASS**
-
-All 9 tasks complete. All 7 spec scenarios have covering tests that pass. All 3 design decisions are implemented correctly and coherently. Typecheck clean; 102/102 tests green. Strict TDD protocol was followed (RED → GREEN → REFACTOR per task). No critical issues, warnings, or suggestions.
-
-**Next recommended**: sdd-archive

package/openspec/specs/core-decoupling/spec.md

@@ -1,110 +0,0 @@
-# Core Decoupling Specification
-
-## Purpose
-
-This spec defines the boundary between the portable core skills engine and the OpenCode-specific adapter in the `opencode-agent-skills-md` package. It guarantees that the core is reusable by any host while OpenCode users see no behavior change. This domain is introduced by the `skills-core-decouple` change; there is no prior baseline to delta against, so this file is the initial full definition.
-
-## Requirements
-
-### Requirement: Core Module Independence (R1)
-
-The `src/core/**` module graph SHALL contain zero runtime imports from `@opencode-ai/plugin`. A static import walk (AST or regex over the compiled dependency graph of `src/core/**`) SHALL fail the build if any such import is detected.
-
-### Requirement: Boundary Interface Location (R2)
-
-The interfaces `SkillHostClient` and `SkillHostSession` SHALL be declared in `src/core/types.ts`. The concrete OpenCode implementation of those interfaces SHALL exist only in `src/opencode/host.ts`. No other module SHALL contain a concrete implementation of either interface.
-
-### Requirement: Backward-Compatible Root Export (R3)
-
-Importing `opencode-agent-skills-md` (the package root) SHALL return the OpenCode plugin with the same shape and behavior as before this change. The four tool names (`use_skill`, `read_skill_file`, `run_skill_script`, `get_available_skills`) SHALL resolve. Additionally, `use_skill` SHALL visibly load a skill: the `onSkillLoaded` callback registered with `createSkillTools` SHALL fire exactly once per successful load per session, the loaded skill's `SKILL.md` content SHALL be injected into the agent context exactly once per session per skill, and the host SHALL observe the loaded-skill state update (TUI icon visible). The callback SHALL be threaded from `src/opencode/plugin.ts` → `createSkillTools` → `UseSkill`.
-
-### Requirement: Framework-Agnostic Subpath Export (R4)
-
-Importing `opencode-agent-skills-md/core` SHALL resolve to the core modules only. A smoke import of the subpath SHALL NOT trigger any side effect, top-level await, or transitive import from `@opencode-ai/plugin`.
-
-### Requirement: Discovery Semantics Preservation (R5)
-
-When the OpenCode adapter delegates to the core's `discoverAllSkills()`, the adapter SHALL observe the same four-location priority and first-match-wins semantics defined by the existing skill behavior. The set of skills surfaced for the baseline fixture locations SHALL match the set surfaced by pre-refactor commit `c2d8e74`. An integration test that mirrors `tests/integration/*` SHALL pass against the new boundary.
-
-### Requirement: Public Surface Freeze (R6)
-
-The four tool names, their parameter shapes, and their user-visible error messages SHALL remain unchanged. Existing tests under `tests/integration/*` and `tests/e2e/*` SHALL pass without modification.
-
-## Scenarios
-
-### Scenario: core is decoupled from the OpenCode SDK
-
-- GIVEN the `src/core/**` module graph is fully composed
-- WHEN a static import walk scans every file in that graph for `from "@opencode-ai/plugin"`
-- THEN zero matches are reported
-- AND the test `tests/core/agnostic.test.ts` passes
-
-### Scenario: opencode host is the only concrete implementation
-
-- GIVEN the interfaces `SkillHostClient` and `SkillHostSession` exist in `src/core/types.ts`
-- WHEN the codebase is searched for classes or factories that implement either interface
-- THEN exactly one match exists, located in `src/opencode/host.ts`
-
-#### Scenario: root export still loads the OpenCode plugin
-
-- GIVEN a consumer imports the package via its root export
-- WHEN the consumer resolves the four tool names from the returned plugin object
-- THEN all four tool names (`use_skill`, `read_skill_file`, `run_skill_script`, `get_available_skills`) are present
-- AND the test-skill load assertion in `tests/integration/startup-smoke.test.ts` passes
-
-#### Scenario: use_skill fires the onSkillLoaded callback
-
-- GIVEN the host registered an `onSkillLoaded` callback via `createSkillTools`
-- WHEN the agent calls `use_skill("test-skill")` on an unloaded skill
-- THEN the callback is invoked exactly once with the loaded skill identifier
-- AND the loaded skill's `SKILL.md` content is present in the agent context
-- AND the host's loaded-skill state reflects the new skill
-
-#### Scenario: use_skill does not re-inject the same skill in one session
-
-- GIVEN the agent has already loaded a given skill via `use_skill` in the current session
-- WHEN the agent calls `use_skill` with the same skill name again in the same session
-- THEN `onSkillLoaded` is NOT re-fired for that skill
-- AND the `SKILL.md` content is NOT re-injected into the context
-
-#### Scenario: missing callback does not break the load
-
-- GIVEN no `onSkillLoaded` is registered with `createSkillTools`
-- WHEN the agent calls `use_skill("any-skill")`
-- THEN the skill still loads and `SKILL.md` content is injected
-- AND no thrown error or unhandled rejection occurs
-
-### Scenario: subpath export does not pull in the OpenCode SDK
-
-- GIVEN a consumer imports `opencode-agent-skills-md/core` in a fresh process
-- WHEN the import resolves and the module graph is recorded
-- THEN no module under `node_modules/@opencode-ai/plugin` appears in the resolved graph
-- AND no side effect from the SDK runs at import time
-
-#### Scenario: discovery priority and first-match-wins are preserved
-
-- GIVEN skill fixtures exist under `.opencode/skills/`, `.claude/skills/`, `~/.config/opencode/skills/`, and `~/.claude/skills/`
-- WHEN the OpenCode adapter calls `discoverAllSkills()`
-- THEN the returned list follows the four-location priority
-- AND duplicate skill names resolve to the first matching location
-- AND the new integration test in `tests/core/` passes
-
-#### Scenario: discoverAllSkills matches the pre-refactor skill set
-
-- GIVEN the same fixture tree used by pre-refactor commit `c2d8e74`
-- WHEN the OpenCode adapter calls `discoverAllSkills()`
-- THEN every skill the baseline surfaced is also surfaced now
-- AND no skill the baseline surfaced is missing from the result
-
-#### Scenario: literal-token search does not drop the pre-refactor skill set
-
-- GIVEN a skill whose trigger tokens are partial substrings of the user's query (not exact match)
-- WHEN the user searches via the literal-token path in `discoverAllSkills()`
-- THEN that skill appears in the result
-- AND the four-location priority remains consistent with first-match-wins
-
-### Scenario: public tool surface is unchanged
-
-- GIVEN the refactor is complete and `pnpm run typecheck` is clean
-- WHEN `pnpm test` runs the existing `tests/integration/*` and `tests/e2e/*` suites
-- THEN all existing assertions on tool names, parameter shapes, and error messages continue to pass without modification

package/packages/core/package.json

@@ -1,30 +0,0 @@
-{
-  "name": "opencode-agent-skills-md-core",
-  "version": "0.0.0",
-  "private": true,
-  "description": "Portable skills engine for opencode-agent-skills-md. Host-agnostic discovery, parsing, search, and host-boundary contracts.",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts",
-      "default": "./src/index.ts"
-    }
-  },
-  "files": [
-    "src"
-  ],
-  "scripts": {
-    "test": "node --import tsx --test \"tests/**/*.test.ts\"",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "yaml": "^2.9.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.9.1",
-    "tsx": "^4.22.3",
-    "typescript": "^6.0.3"
-  }
-}

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

@@ -1,16 +0,0 @@
-/**
- * Content formatting helpers for skill listings and synthetic injections.
- *
- * Pure functions: string assembly only, no host dependencies.
- */
-import type { Skill } from "./types";
-/**
- * Format a list of skills as the inner bullet block used inside the
- * `<available-skills>` synthetic injection.
- */
-export declare function formatSkillListing(skills: Skill[]): string;
-/**
- * Render the full `<available-skills>...</available-skills>` block that the
- * host injects into a session on startup and after compaction.
- */
-export declare function renderAvailableSkillsBlock(skills: Skill[]): string;

package/packages/core/src/content.ts

@@ -1,30 +0,0 @@
-/**
- * Content formatting helpers for skill listings and synthetic injections.
- *
- * Pure functions: string assembly only, no host dependencies.
- */
-
-import type { Skill } from "./types";
-
-/**
- * Format a list of skills as the inner bullet block used inside the
- * `<available-skills>` synthetic injection.
- */
-export const formatSkillListing = (skills: Skill[]): string => {
-  return skills
-    .map((s) => `- ${s.name}: ${s.description}`)
-    .join("\n");
-};
-
-/**
- * Render the full `<available-skills>...</available-skills>` block that the
- * host injects into a session on startup and after compaction.
- */
-export const renderAvailableSkillsBlock = (skills: Skill[]): string => {
-  const skillsList = formatSkillListing(skills);
-  return `<available-skills>
-Use the use_skill, read_skill_file, run_skill_script, and get_available_skills tools to work with skills.
-
-${skillsList}
-</available-skills>`;
-};

package/packages/core/src/debug.ts

@@ -1,16 +0,0 @@
-/**
- * Debug-gated logging for bare `catch {}` blocks.
- *
- * Bare catches stay silent by default so malformed payloads and parse
- * errors never surface as user-visible noise. Setting
- * `OPENCODE_AGENT_SKILLS_DEBUG=1` makes the diagnostic context appear on
- * stderr so developers can trace why a fallback fired.
- *
- * The env var is checked on every call (not cached at module load) so
- * tests can toggle it without re-importing the module.
- */
-export const debugLog = (...args: unknown[]): void => {
-  if (!process.env.OPENCODE_AGENT_SKILLS_DEBUG) return;
-  // eslint-disable-next-line no-console
-  console.error("[opencode-agent-skills-md]", ...args);
-};

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

@@ -1,86 +0,0 @@
-/**
- * Skill discovery across filesystem roots.
- *
- * The core never hard-codes a host's directory layout. Callers pass the list
- * of discovery roots; the default `getDefaultOpencodeRoots` reproduces the
- * legacy OpenCode priority order. PR2 will call `discoverAllSkills` from the
- * OpenCode host adapter with the same default.
- */
-import type { DiscoveryPath, FileDiscoveryResult, LabeledDiscoveryResult, Skill, SkillLabel } from "./types";
-/**
- * Check if a file exists in a directory and return path info.
- *
- * @param directory - Directory to check
- * @param relativePath - Relative path to use in result (caller-specific)
- * @param filename - Name of file to look for (e.g., 'SKILL.md')
- * @returns Path info if file exists, null otherwise
- */
-export declare function findFile(directory: string, relativePath: string, filename: string): Promise<FileDiscoveryResult | null>;
-/**
- * Recursively find SKILL.md files in a directory.
- *
- * The base directory itself is checked first: a SKILL.md placed at the root
- * of a discovery root is returned with `relativePath = ""` and wins the
- * shadowing tie-break over same-name skills in subdirectories (first found
- * wins in `discoverAllSkills`).
- */
-export declare function findSkillsRecursive(baseDir: string, label: SkillLabel, maxDepth?: number): Promise<LabeledDiscoveryResult[]>;
-/**
- * Default discovery roots matching the pre-refactor OpenCode priority order
- * (see commit `c2d8e74`, `src/skills.ts#discoverAllSkills`):
- *   1. .opencode/skills/         (project - OpenCode)
- *   2. .claude/skills/           (project - Claude)
- *   3. ~/.config/opencode/skills/ (user - OpenCode)
- *   4. ~/.claude/skills/         (user - Claude)
- *
- * No shadowing - unique names only. First match wins, duplicates are warned.
- */
-export declare function getDefaultOpencodeRoots(directory: string): DiscoveryPath[];
-/**
- * Default callback for shadowed skill names. Emits a `console.warn` that
- * identifies the surviving (existing) skill and the duplicate that was
- * skipped. Hosts can override by passing `onDuplicate` to `discoverAllSkills`.
- *
- * @internal - exported for testing
- */
-export declare const defaultOnDuplicate: (existing: Skill, duplicate: Skill) => void;
-/**
- * Discover all skills from the provided roots.
- *
- * @param directory - Project directory (used to build the default roots).
- * @param roots - Discovery roots. Defaults to the OpenCode priority order
- *   via `getDefaultOpencodeRoots(directory)`. Hosts pass an explicit list to
- *   override the layout.
- * @param onDuplicate - Optional callback invoked when two roots produce a
- *   skill with the same `name`. Defaults to `console.warn` via
- *   `defaultOnDuplicate`. The first-discovered skill wins; the duplicate
- *   (second one encountered) is passed to the callback but never stored.
- */
-export declare function discoverAllSkills(directory: string, roots?: DiscoveryPath[], onDuplicate?: (existing: Skill, duplicate: Skill) => void): Promise<Map<string, Skill>>;
-/**
- * Resolve a skill by name, handling namespace prefixes.
- * Supports: "skill-name", "project:skill-name", "user:skill-name", etc.
- */
-export declare function resolveSkill(skillName: string, skillsByName: Map<string, Skill>): Skill | null;
-/**
- * Recursively list all files in a directory, returning relative paths.
- * Excludes SKILL.md since it's already loaded as the main content.
- */
-export declare function listSkillFiles(skillPath: string, maxDepth?: number): Promise<string[]>;
-/**
- * Get summaries of all available skills (name, description, trigger).
- * Used by preflight LLM call to evaluate which skills are relevant and
- * by the plugin's keyword matcher to rank matched skills.
- *
- * The `trigger` frontmatter key (PR 2 of `trigger-aware-skill-discovery`)
- * is threaded through so the keyword matcher can apply the 1.5x trigger
- * tier and the targeted outputs can render trigger text.
- *
- * @param directory - Project directory to discover skills from
- * @returns Array of skill summaries
- */
-export declare function getSkillSummaries(directory: string): Promise<Array<{
-    name: string;
-    description: string;
-    trigger?: string;
-}>>;