oricore 1.4.1 → 1.5.1

package/src/skill/bundled.ts

@@ -0,0 +1,225 @@
+import type { Context } from '../core/context';
+import type { SkillMetadata, SkillSource } from './skill';
+
+/**
+ * Bundled skill definition for TypeScript-encoded skills.
+ * This allows skills to be defined programmatically with dynamic behavior.
+ */
+export interface BundledSkillDefinition {
+  /** Unique skill name */
+  name: string;
+  /** Skill description */
+  description: string;
+  /**
+   * Tools that this skill is allowed to use.
+   * If specified, only these tools will be available when the skill executes.
+   */
+  allowedTools?: string[];
+  /**
+   * Execution context for the skill.
+   * - 'inline': Skill content is injected into current conversation (default)
+   * - 'fork': Skill runs in an isolated sub-agent
+   */
+  context?: 'inline' | 'fork';
+  /**
+   * Agent type to use when context is 'fork'.
+   * If not specified, defaults to 'general-purpose'.
+   */
+  agent?: string;
+  /**
+   * Whether this skill can be invoked by users via slash commands.
+   * @default true
+   */
+  userInvocable?: boolean;
+  /**
+   * Whether this skill can be invoked by the model via SkillTool.
+   * @default true
+   */
+  modelInvocable?: boolean;
+  /**
+   * Aliases for the skill name.
+   * Allows the skill to be invoked by alternative names.
+   */
+  aliases?: string[];
+  /**
+   * When to use this skill.
+   * Provides guidance to the model about when to invoke this skill.
+   */
+  whenToUse?: string;
+  /**
+   * Hint for arguments that can be passed to the skill.
+   * Example: '[file_path] [issue_description]'
+   */
+  argumentHint?: string;
+  /**
+   * Function to determine if this skill is enabled in the current context.
+   * Can be a boolean or a function that receives the context.
+   */
+  isEnabled?: boolean | ((context: Context) => boolean);
+  /**
+   * Embedded reference files that will be extracted when the skill runs.
+   * Key is the filename, value is the file content.
+   */
+  files?: Record<string, string>;
+  /**
+   * Generate the skill prompt content.
+   * This function is called when the skill is invoked.
+   * @param args Arguments passed to the skill
+   * @param context The execution context
+   * @returns Promise resolving to the skill prompt content
+   */
+  getPrompt: (args: string, context: Context) => Promise<string> | string;
+}
+
+/**
+ * Registry for bundled skills.
+ * Skills registered here are built into the engine binary.
+ */
+class BundledSkillRegistry {
+  private skills: Map<string, BundledSkillDefinition> = new Map();
+  private aliases: Map<string, string> = new Map();
+
+  /**
+   * Register a bundled skill.
+   * @param definition The skill definition
+   */
+  register(definition: BundledSkillDefinition): void {
+    if (!definition.name) {
+      throw new Error('Bundled skill must have a name');
+    }
+    if (!definition.description) {
+      throw new Error('Bundled skill must have a description');
+    }
+    if (!definition.getPrompt) {
+      throw new Error('Bundled skill must have a getPrompt function');
+    }
+
+    this.skills.set(definition.name, definition);
+
+    // Register aliases
+    if (definition.aliases) {
+      for (const alias of definition.aliases) {
+        this.aliases.set(alias, definition.name);
+      }
+    }
+  }
+
+  /**
+   * Get a bundled skill by name or alias.
+   * @param name Skill name or alias
+   * @returns The skill definition or undefined if not found
+   */
+  get(name: string): BundledSkillDefinition | undefined {
+    // Check direct name first
+    const skill = this.skills.get(name);
+    if (skill) return skill;
+
+    // Check aliases
+    const aliasedName = this.aliases.get(name);
+    if (aliasedName) {
+      return this.skills.get(aliasedName);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get all registered bundled skills.
+   * @param context Optional context to filter by isEnabled
+   * @returns Array of skill definitions
+   */
+  getAll(context?: Context): BundledSkillDefinition[] {
+    return Array.from(this.skills.values()).filter((skill) => {
+      if (skill.isEnabled === undefined) return true;
+      if (typeof skill.isEnabled === 'boolean') return skill.isEnabled;
+      if (typeof skill.isEnabled === 'function' && context) {
+        return skill.isEnabled(context);
+      }
+      return true;
+    });
+  }
+
+  /**
+   * Check if a skill is registered.
+   * @param name Skill name or alias
+   */
+  has(name: string): boolean {
+    return this.skills.has(name) || this.aliases.has(name);
+  }
+
+  /**
+   * Unregister a skill.
+   * @param name Skill name
+   */
+  unregister(name: string): void {
+    const skill = this.skills.get(name);
+    if (skill && skill.aliases) {
+      for (const alias of skill.aliases) {
+        this.aliases.delete(alias);
+      }
+    }
+    this.skills.delete(name);
+  }
+
+  /**
+   * Clear all registered skills.
+   */
+  clear(): void {
+    this.skills.clear();
+    this.aliases.clear();
+  }
+}
+
+// Global registry instance
+export const bundledSkillRegistry = new BundledSkillRegistry();
+
+/**
+ * Convert a bundled skill definition to SkillMetadata format.
+ * This is used internally when loading bundled skills into the SkillManager.
+ */
+export function bundledSkillToMetadata(
+  definition: BundledSkillDefinition,
+  source: SkillSource = 'builtin' as SkillSource,
+): SkillMetadata {
+  return {
+    name: definition.name,
+    description: definition.description,
+    path: `bundled://${definition.name}`,
+    source,
+    allowedTools: definition.allowedTools,
+    context: definition.context,
+    agent: definition.agent,
+    userInvocable: definition.userInvocable ?? true,
+    modelInvocable: definition.modelInvocable ?? true,
+    // Note: bundled skills don't support 'paths' conditional activation
+  };
+}
+
+/**
+ * Helper function to create a simple bundled skill.
+ */
+export function createBundledSkill(
+  config: Omit<BundledSkillDefinition, 'getPrompt'> & {
+    prompt: string | ((args: string, context: Context) => Promise<string> | string);
+  },
+): BundledSkillDefinition {
+  return {
+    ...config,
+    getPrompt:
+      typeof config.prompt === 'string'
+        ? () => config.prompt as string
+        : config.prompt,
+  };
+}
+
+/**
+ * Register a bundled skill using a simplified configuration.
+ */
+export function registerBundledSkill(
+  config: Omit<BundledSkillDefinition, 'getPrompt'> & {
+    prompt: string | ((args: string, context: Context) => Promise<string> | string);
+  },
+): void {
+  const skill = createBundledSkill(config);
+  bundledSkillRegistry.register(skill);
+}

package/src/skill/skill.ts

@@ -6,6 +6,26 @@ import type { Context } from '../core/context';
 import type { Paths } from '../core/paths';
 import { PluginHookType } from '../core/plugin';
 import { safeFrontMatter } from '../utils/safeFrontMatter';
+import {
+  bundledSkillRegistry,
+  bundledSkillToMetadata,
+  type BundledSkillDefinition,
+} from './bundled';
+
+/**
+ * Check if a directory entry is a directory or a symlink pointing to a directory.
+ */
+function isDirOrSymlinkToDir(parentDir: string, entry: fs.Dirent): boolean {
+  if (entry.isDirectory()) return true;
+  if (entry.isSymbolicLink()) {
+    try {
+      return fs.statSync(path.join(parentDir, entry.name)).isDirectory();
+    } catch {
+      // broken symlink, skip
+    }
+  }
+  return false;
+}
 
 export enum SkillSource {
   Plugin = 'plugin',
@@ -13,13 +33,48 @@ export enum SkillSource {
   Global = 'global',
   ProjectClaude = 'project-claude',
   Project = 'project',
+  Builtin = 'builtin',
 }
 
+export type SkillContext = 'inline' | 'fork';
+
 export interface SkillMetadata {
   name: string;
   description: string;
   path: string;
   source: SkillSource;
+  /**
+   * Tools that this skill is allowed to use.
+   * If specified, only these tools will be available when the skill executes.
+   * Example: ['Read', 'Grep', 'Bash']
+   */
+  allowedTools?: string[];
+  /**
+   * Execution context for the skill.
+   * - 'inline': Skill content is injected into current conversation (default)
+   * - 'fork': Skill runs in an isolated sub-agent
+   */
+  context?: SkillContext;
+  /**
+   * Agent type to use when context is 'fork'.
+   * If not specified, defaults to a general-purpose agent.
+   */
+  agent?: string;
+  /**
+   * File path patterns that trigger this skill's availability.
+   * Example: ['src/asterisk/asterisk.ts', '*.test.js']
+   */
+  paths?: string[];
+  /**
+   * Whether this skill can be invoked by users via slash commands.
+   * @default true
+   */
+  userInvocable?: boolean;
+  /**
+   * Whether this skill can be invoked by the model via SkillTool.
+   * @default true
+   */
+  modelInvocable?: boolean;
 }
 
 export interface SkillError {
@@ -71,26 +126,149 @@ export class SkillManager {
   private errors: SkillError[] = [];
   private paths: Paths;
   private context: Context;
+  /**
+   * Tracks which skills are currently "active" based on file operations.
+   * Skills with `paths` frontmatter are activated when matching files are accessed.
+   */
+  private activeSkillNames: Set<string> = new Set();
+  /**
+   * Maps alias names to original skill names for bundled skills.
+   */
+  private aliasMap: Map<string, string> = new Map();
 
   constructor(opts: SkillManagerOpts) {
     this.context = opts.context;
     this.paths = opts.context.paths;
   }
 
-  getSkills(): SkillMetadata[] {
-    return Array.from(this.skillsMap.values());
+  /**
+   * Get all loaded skills.
+   * @param options Filter options
+   * @returns Array of skill metadata
+   */
+  getSkills(options?: {
+    /** Only return skills that are user-invocable */
+    userInvocable?: boolean;
+    /** Only return skills that are model-invocable */
+    modelInvocable?: boolean;
+    /** Only return active skills (those with matching paths) */
+    activeOnly?: boolean;
+  }): SkillMetadata[] {
+    let skills = Array.from(this.skillsMap.values());
+
+    if (options?.userInvocable !== undefined) {
+      skills = skills.filter(
+        (s) => (s.userInvocable ?? true) === options.userInvocable,
+      );
+    }
+
+    if (options?.modelInvocable !== undefined) {
+      skills = skills.filter(
+        (s) => (s.modelInvocable ?? true) === options.modelInvocable,
+      );
+    }
+
+    if (options?.activeOnly) {
+      skills = skills.filter((s) => this.activeSkillNames.has(s.name));
+    }
+
+    return skills;
   }
 
+  /**
+   * Get a specific skill by name.
+   * Automatically resolves aliases to the original skill.
+   * @param name Skill name or alias
+   * @returns Skill metadata or undefined if not found
+   */
   getSkill(name: string): SkillMetadata | undefined {
-    return this.skillsMap.get(name);
+    // Check direct name first
+    const skill = this.skillsMap.get(name);
+    if (skill) return skill;
+
+    // Check if it's an alias
+    const originalName = this.aliasMap.get(name);
+    if (originalName) {
+      return this.skillsMap.get(originalName);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Check if a skill is active (has matching paths for current context).
+   * @param name Skill name
+   */
+  isSkillActive(name: string): boolean {
+    return this.activeSkillNames.has(name);
+  }
+
+  /**
+   * Activate skills based on file paths.
+   * Skills with `paths` frontmatter that match the given paths will be activated.
+   * @param filePaths Array of file paths to check
+   * @returns Array of newly activated skill names
+   */
+  activateSkillsForPaths(filePaths: string[]): string[] {
+    const newlyActivated: string[] = [];
+    const minimatch = require('minimatch');
+
+    for (const [name, skill] of this.skillsMap) {
+      if (skill.paths && skill.paths.length > 0) {
+        const isMatch = skill.paths.some((pattern) =>
+          filePaths.some((filePath) => minimatch(filePath, pattern)),
+        );
+
+        if (isMatch && !this.activeSkillNames.has(name)) {
+          this.activeSkillNames.add(name);
+          newlyActivated.push(name);
+        }
+      }
+    }
+
+    return newlyActivated;
+  }
+
+  /**
+   * Clear all active skill activations.
+   * Useful when switching contexts or projects.
+   */
+  clearActiveSkills(): void {
+    this.activeSkillNames.clear();
+  }
+
+  /**
+   * Get all skills that have path-based conditional activation.
+   * @returns Array of skills with paths defined
+   */
+  getConditionalSkills(): SkillMetadata[] {
+    return Array.from(this.skillsMap.values()).filter(
+      (s) => s.paths && s.paths.length > 0,
+    );
   }
 
   getErrors(): SkillError[] {
     return this.errors;
   }
 
-  async readSkillBody(skill: SkillMetadata): Promise<string> {
+  /**
+   * Read the body content of a skill.
+   * For file-based skills, reads from disk.
+   * For bundled skills, generates content via getPrompt.
+   */
+  async readSkillBody(skill: SkillMetadata, args: string = ''): Promise<string> {
     try {
+      // Handle bundled skills
+      if (skill.path.startsWith('bundled://')) {
+        const bundledName = skill.path.replace('bundled://', '');
+        const bundledSkill = bundledSkillRegistry.get(bundledName);
+        if (!bundledSkill) {
+          throw new Error(`Bundled skill "${bundledName}" not found in registry`);
+        }
+        return await bundledSkill.getPrompt(args, this.context);
+      }
+
+      // Handle file-based skills
       const content = fs.readFileSync(skill.path, 'utf-8');
       const { body } = safeFrontMatter(content, skill.path);
       return body;
@@ -101,10 +279,32 @@ export class SkillManager {
     }
   }
 
+  /**
+   * Get a bundled skill definition by name.
+   * @param name Bundled skill name
+   * @returns Bundled skill definition or undefined if not found
+   */
+  getBundledSkill(name: string): BundledSkillDefinition | undefined {
+    return bundledSkillRegistry.get(name);
+  }
+
+  /**
+   * Register a bundled skill programmatically.
+   * @param definition Bundled skill definition
+   */
+  registerBundledSkill(definition: BundledSkillDefinition): void {
+    bundledSkillRegistry.register(definition);
+    // Reload to include the new skill
+    this.loadBuiltinSkills();
+  }
+
   async loadSkills(): Promise<void> {
     this.skillsMap.clear();
     this.errors = [];
 
+    // Load builtin/bundled skills first
+    this.loadBuiltinSkills();
+
     const pluginSkills = await this.context.apply({
       hook: 'skill',
       args: [],
@@ -153,6 +353,27 @@ export class SkillManager {
     this.loadSkillsFromDirectory(projectDir, SkillSource.Project);
   }
 
+  /**
+   * Load builtin/bundled skills from the registry.
+   */
+  private loadBuiltinSkills(): void {
+    // Clear alias map when reloading
+    this.aliasMap.clear();
+
+    const bundledSkills = bundledSkillRegistry.getAll(this.context);
+    for (const skill of bundledSkills) {
+      const metadata = bundledSkillToMetadata(skill, SkillSource.Builtin);
+      this.skillsMap.set(skill.name, metadata);
+
+      // Register aliases in the alias map
+      if (skill.aliases) {
+        for (const alias of skill.aliases) {
+          this.aliasMap.set(alias, skill.name);
+        }
+      }
+    }
+  }
+
   private loadSkillsFromDirectory(
     skillsDir: string,
     source: SkillSource,
@@ -165,7 +386,7 @@ export class SkillManager {
       const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
 
       for (const entry of entries) {
-        if (entry.isDirectory()) {
+        if (isDirOrSymlinkToDir(skillsDir, entry)) {
           const skillPath = path.join(skillsDir, entry.name, 'SKILL.md');
           if (fs.existsSync(skillPath)) {
             this.loadSkillFile(skillPath, source);
@@ -210,6 +431,12 @@ export class SkillManager {
       const { attributes } = safeFrontMatter<{
         name?: string;
         description?: string;
+        allowedTools?: string | string[];
+        context?: string;
+        agent?: string;
+        paths?: string | string[];
+        userInvocable?: boolean;
+        modelInvocable?: boolean;
       }>(content, skillPath);
 
       if (!attributes.name) {
@@ -252,10 +479,28 @@ export class SkillManager {
         return null;
       }
 
+      // Parse allowedTools - supports both string and array formats
+      const allowedTools = this.parseStringArrayField(attributes.allowedTools);
+
+      // Parse context (inline or fork)
+      const context: SkillContext | undefined =
+        attributes.context === 'inline' || attributes.context === 'fork'
+          ? attributes.context
+          : undefined;
+
+      // Parse paths - supports both string and array formats
+      const paths = this.parseStringArrayField(attributes.paths);
+
       return {
         name: attributes.name,
         description: attributes.description,
         path: skillPath,
+        allowedTools,
+        context,
+        agent: attributes.agent,
+        paths,
+        userInvocable: attributes.userInvocable ?? true,
+        modelInvocable: attributes.modelInvocable ?? true,
       };
     } catch (error) {
       this.errors.push({
@@ -269,6 +514,32 @@ export class SkillManager {
     }
   }
 
+  /**
+   * Parse a field that can be either a comma-separated string or an array of strings.
+   * @param value The value to parse
+   * @returns Array of strings or undefined if empty
+   */
+  private parseStringArrayField(
+    value: string | string[] | undefined,
+  ): string[] | undefined {
+    if (!value) return undefined;
+
+    if (Array.isArray(value)) {
+      return value
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    }
+
+    if (typeof value === 'string') {
+      return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    }
+
+    return undefined;
+  }
+
   async addSkill(
     source: string,
     options: AddSkillOptions = {},
@@ -457,7 +728,7 @@ export class SkillManager {
     if (fs.existsSync(skillsDir) && fs.statSync(skillsDir).isDirectory()) {
       const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
       for (const entry of entries) {
-        if (entry.isDirectory()) {
+        if (isDirOrSymlinkToDir(skillsDir, entry)) {
           const skillPath = path.join(skillsDir, entry.name, 'SKILL.md');
           if (fs.existsSync(skillPath)) {
             skills.push(skillPath);
@@ -471,7 +742,7 @@ export class SkillManager {
 
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory()) {
+      if (isDirOrSymlinkToDir(dir, entry)) {
         const skillPath = path.join(dir, entry.name, 'SKILL.md');
         if (fs.existsSync(skillPath)) {
           skills.push(skillPath);

package/src/tools/tool.ts

@@ -51,9 +51,6 @@ export async function resolveTools(opts: ResolveToolsOpts) {
     createGlobTool({ cwd }),
     createGrepTool({ cwd }),
     createFetchTool({ model, fetch: opts.context.fetch }),
-    ...(hasSkills
-      ? [createSkillTool({ skillManager: opts.context.skillManager! })]
-      : []),
   ];
   const askUserQuestionTools = opts.askUserQuestion
     ? [createAskUserQuestionTool()]
@@ -90,7 +87,7 @@ export async function resolveTools(opts: ResolveToolsOpts) {
 
   const mcpTools = await getMcpTools(opts.context);
 
-  const allTools = [
+  let allTools = [
     ...readonlyTools,
     ...askUserQuestionTools,
     ...writeTools,
@@ -99,6 +96,19 @@ export async function resolveTools(opts: ResolveToolsOpts) {
     ...mcpTools,
   ];
 
+  // Add skill tool if skills are available
+  // Note: skill tool is added after initial tool list so it can reference allTools for fork execution
+  if (hasSkills) {
+    const skillTool = createSkillTool({
+      skillManager: opts.context.skillManager!,
+      context: opts.context,
+      tools: allTools,
+      sessionId: opts.sessionId,
+      signal: opts.signal,
+    });
+    allTools = [...allTools, skillTool];
+  }
+
   // 1. First, execute plugin hook to allow plugins to add/modify tools
   let availableTools = allTools;
   try {