opencode-dynamic-skills 1.0.0

package/dist/lib/Identifiers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a query string to match against toolName paths
+ * Converts slashes and hyphens to underscores for prefix matching
+ */
+export declare function normalizePathQuery(query: string): string;
+/**
+ * Strip the "skills_" prefix from toolName for user-facing matching
+ */
+export declare function stripSkillsPrefix(toolName: string): string;
+/**
+ * Generate tool name from skill path
+ * Examples:
+ *   skills/brand-guidelines/SKILL.md → skills_brand_guidelines
+ *   skills/document-skills/docx/SKILL.md → skills_document_skills_docx
+ *   skills/image-processing/SKILL.md → skills_image_processing
+ */
+export declare function toolName(skillPath: string): string;

package/dist/lib/Indentifiers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/OpenCodeChat.d.ts

@@ -0,0 +1,5 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+export declare function createInstructionInjector(ctx: PluginInput): (text: string, props: {
+    sessionId: string;
+    agent: string;
+}) => Promise<void>;

package/dist/lib/OpenCodeChat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/ReadyStateMachine.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ReadyStateMachine - Async Initialization State Coordinator
+ *
+ * WHY: Tools need to wait for the skill registry to finish async discovery and
+ * parsing before they can execute. This state machine coordinates that initialization
+ * without requiring callers to manage Promise chains manually.
+ *
+ * DESIGN: Implements a simple state machine with watchers pattern for notification.
+ * State transitions: idle → loading → (ready|error)
+ *
+ * CONTRACT:
+ * - setStatus(): update internal state and notify all watchers
+ * - watchReady(callback): subscribe to state changes, returns unsubscribe function
+ * - whenReady(): blocking async method that resolves when state is ready, rejects if error
+ *
+ * WHY NOT A SIMPLE PROMISE:
+ * - Promise resolves once, but multiple tools may call whenReady() at different times
+ * - This pattern allows multiple concurrent waiters without race conditions
+ * - Supports reversible state (could transition back to loading if needed)
+ *
+ * EXAMPLE:
+ *   const ready = createReadyStateMachine();
+ *   ready.setStatus('loading');
+ *   // ... do async work ...
+ *   ready.setStatus('ready');
+ *
+ *   // Tool execution:
+ *   await ready.whenReady(); // blocks until ready
+ *   // ... now safe to execute ...
+ */
+export type ReadyStateMachine = ReturnType<typeof createReadyStateMachine>;
+export declare function createReadyStateMachine(): {
+    setStatus: (newStatus: "idle" | "loading" | "ready" | "error") => void;
+    watchReady: (callback: (status: "idle" | "loading" | "ready" | "error") => void) => () => void;
+    whenReady: () => Promise<void>;
+};

package/dist/lib/SkillFs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SkillFs - Abstract filesystem access for skills
+ *
+ * This module encapsulates all filesystem operations related to skill discovery and loading.
+ * It provides a mockable interface that works across different Node.js implementations,
+ * enabling unit tests to stub filesystem operations without complex mocking libraries.
+ *
+ * Each function is designed as a pure export to be easily replaced in test environments
+ * (e.g., via mocking FS access in test suites).
+ */
+export declare const readSkillFile: (path: string) => Promise<string>;
+/**
+ * List all files in a skill subdirectory (e.g., scripts/, resources/)
+ * Returns a flat array of absolute file paths
+ *
+ * @param skillPath - Base path to the skill directory
+ * @param subdirectory - Subdirectory to scan (e.g., 'scripts', 'resources')
+ * @returns Array of absolute file paths
+ */
+export declare const listSkillFiles: (skillPath: string, subdirectory: string) => string[];
+export declare const findSkillPaths: (basePath: string) => Promise<string[]>;
+export declare const doesPathExist: (path: string) => boolean;
+/**
+ * Detect MIME type from file extension
+ * Used for skill resources to identify content type
+ *
+ * @param filePath - Path to the file
+ * @returns MIME type string
+ */
+export declare const detectMimeType: (filePath: string) => string;

package/dist/lib/createPromptRenderer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Prompt Renderer Factory
+ *
+ * WHY: Factory pattern centralizes renderer instantiation and makes it easy to:
+ * - Add new renderer types in the future
+ * - Test with different renderers
+ * - Handle invalid formats gracefully
+ */
+/**
+ * Create a prompt renderer for the specified format
+ *
+ * @param format The desired format: 'json' | 'xml' | 'md'
+ * @returns A PromptRenderer instance for the specified format
+ * @throws Error if format is not recognized
+ */
+export declare function createPromptRenderer(): {
+    getFormatter: (format: "json" | "xml" | "md") => (args: {
+        data: import("../types").Skill;
+        type: "Skill";
+    } | {
+        data: {
+            skill_name: string;
+            resource_path: string;
+            resource_mimetype: string;
+            content: string;
+        };
+        type: "SkillResource";
+    } | {
+        data: {
+            mode?: "search" | "recommend";
+            query: string | string[];
+            skills: Array<{
+                name: string;
+                description: string;
+            }>;
+            summary: {
+                total: number;
+                matches: number;
+                feedback: string;
+            };
+            recommendations?: Array<{
+                name: string;
+                description: string;
+                score: number;
+                reason: string;
+            }>;
+            guidance?: string;
+            debug?: import("../types").SkillRegistryDebugInfo;
+        };
+        type: "SkillSearchResults";
+    }) => string;
+};

package/dist/lib/createPromptRenderer.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * createPromptRenderer Factory Tests
+ *
+ * Test coverage:
+ * - Correct renderer instantiation for each format
+ * - Invalid format error handling
+ * - Format identifier verification
+ */
+export {};

package/dist/lib/getModelFormat.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Model Format Resolver - Select renderer based on active LLM model
+ *
+ * WHY: Different LLM models have different preferences and strengths:
+ * - Claude models: optimized for XML, prefer structured XML injection
+ * - GPT models: strong JSON parsing, prefer JSON-formatted data
+ * - Other models: may benefit from markdown readability
+ *
+ * This function detects the active model and selects the configured
+ * format preference for that model, falling back to progressively more
+ * generic model patterns.
+ *
+ * HOW IT WORKS:
+ * 1. Query the current session via client.session.message()
+ * 2. Extract the modelID from the response (e.g., "anthropic-claude-3-5-sonnet")
+ * 3. Try matching in order:
+ *    - Full model ID (e.g., "anthropic-claude-3-5-sonnet")
+ *    - Generic model pattern (e.g., "claude-3-5-sonnet")
+ * 4. If no match, fall back to promptRenderer default
+ */
+import type { PluginConfig } from '../types';
+/**
+ * Resolve the appropriate prompt format for the current model
+ *
+ * @param args An object containing:
+ *   - modelId?: The identifier of the active model (e.g., "claude-3-5-sonnet")
+ *   - providerId?: The identifier of the model provider (e.g., "anthropic")
+ *   - config: The plugin configuration (has promptRenderer and modelRenderers)
+ * @returns The format to use: 'json' | 'xml' | 'md'
+ */
+export declare function getModelFormat(args: {
+    modelId?: string;
+    providerId?: string;
+    config: PluginConfig;
+}): 'json' | 'xml' | 'md';

package/dist/lib/renderers/JsonPromptRenderer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JsonPromptRenderer - Format objects as JSON
+ *
+ * WHY: Some LLM models (especially GPT family) have strong JSON parsing
+ * and prefer structured JSON data over XML for reliability and clarity.
+ */
+import type { PromptRenderer } from '../../types';
+export declare const createJsonPromptRenderer: () => PromptRenderer;

package/dist/lib/renderers/JsonPromptRenderer.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * JsonPromptRenderer Tests
+ *
+ * Test coverage for real use cases:
+ * - Rendering Skill objects for prompt injection
+ * - Rendering SkillResource objects (file content)
+ * - Rendering SkillSearchResults objects (search results)
+ * - Proper JSON formatting with indentation
+ */
+export {};

package/dist/lib/renderers/MdPromptRenderer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * MdPromptRenderer - Format objects as human-readable Markdown
+ *
+ * WHY: Markdown provides human-readable formatting that works well for:
+ * - Models that benefit from visual structure and readability
+ * - Debugging and development (easier to read in logs)
+ * - Accessibility and presentation
+ *
+ * STRUCTURE:
+ * - Top-level keys → H3 headings (### key)
+ * - Nested objects → H4 headings (#### key) with increased indentation
+ * - Leaf nodes → nested bullet list items with emphasis: - **key**: *value*
+ * - Arrays → nested bullets under parent key
+ * - Special characters → HTML-escaped (<, >, &)
+ * - Skill content → appended after --- separator with ### Content heading
+ */
+import type { PromptRenderer } from '../../types';
+export declare const createMdPromptRenderer: () => PromptRenderer;

package/dist/lib/renderers/MdPromptRenderer.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MdPromptRenderer Tests
+ *
+ * Test coverage for real use cases:
+ * - Rendering Skill objects with metadata, references, scripts, assets
+ * - Rendering SkillResource objects (file content)
+ * - Rendering SkillSearchResults objects
+ * - HTML character escaping for security
+ * - Special values handling (null, undefined)
+ */
+export {};

package/dist/lib/renderers/XmlPromptRenderer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * XmlPromptRenderer - Format objects as XML (current default)
+ *
+ * WHY: Claude models are trained extensively on XML and prefer structured
+ * XML injection for skill metadata and search results. This maintains the
+ * current behavior as the default and recommended format for Claude models.
+ */
+import type { PromptRenderer } from '../../types';
+export declare const createXmlPromptRenderer: () => PromptRenderer;

package/dist/lib/renderers/XmlPromptRenderer.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * XmlPromptRenderer Tests
+ *
+ * Test coverage for real use cases:
+ * - Rendering Skill objects as XML with resource maps converted to arrays
+ * - Rendering SkillResource objects (file content)
+ * - Rendering SkillSearchResults objects
+ * - XML character escaping for security
+ * - Resource map serialization
+ */
+export {};

package/dist/lib/renderers/resourceMapToArray.d.ts

@@ -0,0 +1,2 @@
+import { MapValue, SkillResourceMap } from '../../types';
+export declare const resourceMapToArray: (resources: SkillResourceMap) => MapValue<SkillResourceMap>[];

package/dist/lib/xml.d.ts

@@ -0,0 +1 @@
+export declare function jsonToXml(json: object, rootElement?: string): string;

package/dist/mocks.d.ts

@@ -0,0 +1,32 @@
+import type { Skill, SkillRegistry, SkillRegistryController, SkillSearchResult } from './types';
+/**
+ * Creates a mock Skill object with sensible defaults
+ * @param overrides Partial skill properties to override defaults
+ * @returns A complete Skill object
+ */
+export declare function createMockSkill(overrides?: Partial<Skill>): Skill;
+/**
+ * Creates a mock SkillRegistryController
+ * @param skills Array of skills to include in the registry
+ * @returns A mock registry controller
+ */
+export declare function createMockRegistryController(skills?: Skill[]): SkillRegistryController;
+/**
+ * Creates a mock SkillProvider with a registry controller
+ * @param skills Array of skills to include in the provider
+ * @returns A mock skill provider
+ */
+export declare function createMockRegistry(skills?: Skill[]): Promise<SkillRegistry>;
+/**
+ * Creates a mock SkillSearchResult
+ * @param overrides Partial search result properties to override defaults
+ * @returns A mock search result
+ */
+export declare function mockSearchResult(overrides?: Partial<SkillSearchResult>): SkillSearchResult;
+/**
+ * Creates a fully configured mock search result with skill matches and metadata
+ * @param skills Array of skill matches to include in the result
+ * @param overrides Additional overrides for search result properties
+ * @returns A complete search result with proper structure
+ */
+export declare function mockFullSearchResult(skills?: Skill[], overrides?: Partial<SkillSearchResult>): SkillSearchResult;

package/dist/mocks.skillfs.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/MessageModelIdAccountant.d.ts

@@ -0,0 +1,22 @@
+declare function createMessageModelIdAccountant(): {
+    reset: () => void;
+    track: (info: {
+        sessionID: string;
+        messageID: string;
+        modelID: string;
+        providerID: string;
+    }) => void;
+    untrackMessage: (args: {
+        messageID: string;
+        sessionID: string;
+    }) => void;
+    untrackSession: (sessionID: string) => void;
+    getModelInfo: (args: {
+        messageID: string;
+        sessionID: string;
+    }) => {
+        modelID: string;
+        providerID: string;
+    } | undefined;
+};
+export { createMessageModelIdAccountant };

package/dist/services/SkillRegistry.d.ts

@@ -0,0 +1,9 @@
+import { PluginConfig, PluginLogger, SkillRegistry, SkillRegistryController, SkillResourceMap } from '../types';
+export declare const stripTrailingPathSeparators: (path: string) => string;
+export declare const suggestSkillsDirectoryPath: (path: string) => string | null;
+export declare function createSkillRegistryController(): SkillRegistryController;
+/**
+ * SkillRegistry manages skill discovery and parsing
+ */
+export declare function createSkillRegistry(config: PluginConfig, logger: PluginLogger): Promise<SkillRegistry>;
+export declare function createSkillResourceMap(skillPath: string, filePaths: string[]): SkillResourceMap;

package/dist/services/SkillRegistry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/SkillResourceResolver.d.ts

@@ -0,0 +1,20 @@
+import type { SkillRegistry } from '../types';
+export declare function normalizeSkillResourcePath(inputPath: string): string;
+/**
+ * Skill resources are mapped on startup as a dictionary of relative paths to resource metadata.
+ *
+ * This resolver uses that mapping to solve several things:
+ *
+ * - locate and read the actual resource files.
+ * - ensure the requested path isn't outside the skill directory (security).
+ * - return the content and mime type of the resource.
+ */
+export declare function createSkillResourceResolver(provider: SkillRegistry): (args: {
+    skill_name: string;
+    type?: string;
+    relative_path: string;
+}) => Promise<{
+    absolute_path: string;
+    content: string;
+    mimeType: string;
+}>;

package/dist/services/SkillResourceResolver.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/SkillSearcher.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SkillSearcher - Natural Language Query Parser and Skill Ranking Engine
+ *
+ * WHY: Users expect Gmail-style search syntax (quoted phrases, negation, multiple terms).
+ * This module abstracts the search-string library and implements skill-specific ranking.
+ *
+ * SEARCH STRATEGY:
+ * 1. Parse user query into include/exclude terms (using search-string for Gmail syntax)
+ * 2. Filter: ALL include terms must appear in skill (name, description, or toolName)
+ * 3. Exclude: Remove matches that contain any exclude term
+ * 4. Rank: Score by match location (name matches weighted 3×, description 1×)
+ * 5. Sort: By total score (desc) → name matches (desc) → alphabetically
+ *
+ * QUERY INTERPRETATION:
+ * - "git commit" → include: [git, commit]
+ * - "git -rebase" → include: [git], exclude: [rebase]
+ * - '"git rebase"' → include: [git rebase] (phrase, no split)
+ * - "*" or empty → list all skills
+ *
+ * RANKING ALGORITHM:
+ * - Name match: +3 per term found in skill name
+ * - Description match: +1 per term found in description
+ * - Exact name match: +10 bonus
+ * - Final sort: highest score first, tie-break by name matches, then alphabetical
+ *
+ * WHY SEARCH-STRING: Handles complex syntax edge cases (quotes, escaped chars)
+ * without rolling our own parser. Proven in production systems (Gmail, etc).
+ *
+ * WHY NO PARTIAL MATCHING: "python" won't match "python-docstring" because we check
+ * term-by-term inclusion, not word-level matching. This matches user expectations
+ * (they searched for "python", not "python-" or "pythonish").
+ */
+import type { Skill, ParsedSkillQuery, SkillRank, SkillRegistryController, SkillSearcher } from '../types';
+/**
+ * Parse a user query into structured search terms
+ */
+export declare function parseQuery(queryString: string | string[]): ParsedSkillQuery;
+/**
+ * Calculate ranking score for a skill against query terms
+ *
+ * SCORING FORMULA:
+ * - nameMatches: number of include terms found in skill name (0 or more)
+ * - descMatches: number of include terms found in description (0 or more)
+ * - totalScore = (nameMatches × 3) + (descMatches × 1) + exactBonus
+ * - exactBonus: +10 if query is single term and equals skill name exactly
+ *
+ * WHY THIS WEIGHTING:
+ * - Skill name is a strong signal (3× weight) because it's the identifier
+ * - Description matches are weaker (1× weight) because skill names vary
+ * - Exact match bonus breaks ties and promotes direct matches to top
+ *
+ * EXAMPLE:
+ * - Query: "git" | Skill name: "writing-git-commits" | Score: 3 (name match)
+ * - Query: "git" | Skill name: "git" | Score: 13 (name match + exact bonus)
+ * - Query: "revert changes" | Skill name: "git-revert" | Description: "Revert..."
+ *   | Score: 4 (1 name match + 1 desc match + 2 bonus doesn't apply)
+ */
+export declare function rankSkill(skill: Skill, includeTerms: string[]): SkillRank;
+/**
+ * Filter out skills matching exclusion terms
+ */
+export declare function shouldIncludeSkill(skill: Skill, excludeTerms: string[]): boolean;
+/**
+ * Generate user-friendly feedback about query interpretation
+ */
+export declare function generateFeedback(query: ParsedSkillQuery, matchCount: number): string;
+/**
+ * SkillSearcher - Natural Language Query Parser for Skills
+ *
+ * Provides clean abstraction over search-string library for skill discovery.
+ * Handles query parsing, ranking, and result formatting with support for:
+ * - Natural syntax (Gmail-style)
+ * - Negation (-term)
+ * - Quoted phrases
+ * - Multiple search terms (AND logic)
+ */
+export declare function createSkillSearcher(registry: SkillRegistryController): SkillSearcher;

package/dist/services/SkillSearcher.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/SkillSearcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/logger.d.ts

@@ -0,0 +1,2 @@
+import { PluginConfig, PluginLogger } from '../types';
+export declare function createLogger(config: PluginConfig): PluginLogger;

package/dist/tools/SkillFinder.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SkillFinder Tool - Natural Language Skill Discovery
+ *
+ * WHY: This tool wraps SkillSearcher with ready-state synchronization.
+ * Users call skill_find("git commits") to search for relevant skills.
+ * The tool must block until the registry is fully initialized before searching.
+ *
+ * CRITICAL PATTERN: `await provider.controller.ready.whenReady()`
+ * This line ensures that skill discovery has completed before we attempt to
+ * search. Without this, early calls would search an empty registry.
+ *
+ * RETURN VALUE: Object with:
+ * - query: original query for user reference
+ * - skills: matched skills with toolName and description
+ * - summary: metadata (total skills, matches found, feedback message)
+ * - debug: registry debug info (only if enabled in config)
+ *
+ * TOOL REGISTRATION: This factory is called in api.ts like:
+ *   findSkills: createSkillFinder(registry)
+ * Which returns an async function that OpenCode registers as a tool.
+ *
+ * FEEDBACK: The feedback message explains the query interpretation to the user:
+ *   "Searching for: **git commit** | Found 3 matches"
+ *
+ * @param provider SkillRegistry instance (must be initialized first)
+ * @returns Async function callable by OpenCode as skill_find tool
+ */
+import type { SkillRegistry } from '../types';
+/**
+ * Creates a tool function that searches for skills
+ */
+export declare function createSkillFinder(provider: SkillRegistry): (args: {
+    query: string | string[];
+}) => Promise<{
+    query: string | string[];
+    skills: {
+        name: string;
+        description: string;
+    }[];
+    summary: {
+        total: number;
+        matches: number;
+        feedback: string;
+    };
+    debug: import("../types").SkillRegistryDebugInfo | undefined;
+}>;

package/dist/tools/SkillRecommender.d.ts

@@ -0,0 +1,25 @@
+import type { SkillRegistry } from '../types';
+export declare function createSkillRecommender(provider: SkillRegistry): (args: {
+    task: string;
+    limit?: number;
+}) => Promise<{
+    mode: "recommend";
+    query: string;
+    skills: {
+        name: string;
+        description: string;
+    }[];
+    recommendations: {
+        name: string;
+        description: string;
+        score: number;
+        reason: string;
+    }[];
+    guidance: string;
+    summary: {
+        total: number;
+        matches: number;
+        feedback: string;
+    };
+    debug: import("../types").SkillRegistryDebugInfo | undefined;
+}>;

package/dist/tools/SkillRecommender.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/SkillResourceReader.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SkillResourceReader Tool - Safe Skill Resource Access
+ *
+ * WHY: Skills contain resources (scripts, assets, references) that need to be
+ * retrieved safely. This tool:
+ * 1. Validates the resource type (scripts|assets|references)
+ * 2. Resolves the path safely (prevents path traversal attacks)
+ * 3. Reads the file content and returns it for injection
+ *
+ * CRITICAL SECURITY: Resources are pre-indexed at parse time. This tool can only
+ * retrieve resources that were explicitly registered in the skill's resource maps.
+ * It cannot request arbitrary paths like "../../etc/passwd".
+ *
+ * PATH PARSING: Input path format is "type/relative/path"
+ * - type: one of 'scripts', 'assets', 'references' (validated)
+ * - relative/path: path within that type's directory
+ *
+ * EXAMPLE:
+ * - Args: { skill_name: 'git-commit', relative_path: 'scripts/commit.sh' }
+ * - Type: 'scripts', path: 'commit.sh'
+ * - Resolves: skill.scripts.get('commit.sh') → reads file content
+ *
+ * RETURN VALUE: Object with:
+ * - injection: contains skill_name, resource_path, MIME type, and content
+ * The caller (index.ts) injects this content into the message body
+ *
+ * READY STATE: Must wait for registry initialization before accessing skills
+ *
+ * @param provider SkillRegistry instance (must be initialized first)
+ * @returns Async function callable by OpenCode as skill_resource tool
+ */
+import { SkillRegistry } from '../types';
+export declare function createSkillResourceReader(provider: SkillRegistry): (args: {
+    skill_name: string;
+    relative_path: string;
+}) => Promise<{
+    injection: {
+        skill_name: string;
+        resource_path: string;
+        resource_mimetype: string;
+        content: string;
+    };
+}>;

package/dist/tools/SkillUser.d.ts

@@ -0,0 +1,5 @@
+import type { Skill, SkillRegistry } from '../types';
+export declare function createSkillLoader(provider: SkillRegistry): (skillNames: string[]) => Promise<{
+    loaded: Skill[];
+    notFound: string[];
+}>;