invoke_skill

Instructions

Implementation Reference

• src/services/skill-executor.ts:14-48 (handler)

  The actual implementation of invoke_skill logic. Looks up the skill by ID from the registry, validates parameters via registry, substitutes {{param}} and ${param} placeholders with provided values, and returns the formatted content with execution time.

  async invokeSkill(skillId: string, parameters: Record<string, unknown> = {}): Promise<InvocationResult> {
    const startTime = Date.now();
  
    try {
      // Check if skill exists
      const skill = this.registry.getSkill(skillId);
      if (!skill) {
        const executionTime = Date.now() - startTime;
        logger.warn(`Skill not found: ${skillId}`);
        return createErrorResult('SkillNotFound', `Skill not found: ${skillId}`, executionTime);
      }
  
      // Validate parameters
      const validation = this.registry.validateParameters(skillId, parameters);
      if (!validation.valid) {
        const executionTime = Date.now() - startTime;
        const errorMessage = validation.errors?.join(', ') || 'Parameter validation failed';
        logger.warn(`Parameter validation failed for skill ${skillId}: ${errorMessage}`);
        return createErrorResult('InvalidParams', errorMessage, executionTime, { errors: validation.errors });
      }
  
      // Substitute parameters into skill content
      const formattedContent = this.substituteParameters(skill.content, parameters);
  
      const executionTime = Date.now() - startTime;
      logger.debug(`Skill ${skillId} invoked successfully in ${executionTime}ms`);
  
      return createSuccessResult(formattedContent, executionTime);
    } catch (error) {
      const executionTime = Date.now() - startTime;
      const errorMessage = error instanceof Error ? error.message : String(error);
      logger.error(`Error invoking skill ${skillId}:`, error);
      return createErrorResult('ExecutionError', errorMessage, executionTime);
    }
  }

• src/models/skill.ts:37-42 (schema)

  InvocationResult schema (Zod) defining the output shape: success boolean, optional content string, optional error object (code, message, details), and executionTime number.

  export const invocationResultSchema = z.object({
    success: z.boolean(),
    content: z.string().optional(),
    error: invocationErrorSchema.optional(),
    executionTime: z.number().int().min(0),
  });

• src/models/skill.ts:29-33 (schema)

  InvocationError schema (Zod) defining the error structure with code (enum of error types), message, and optional details.

  export const invocationErrorSchema = z.object({
    code: z.enum(['InvalidParams', 'SkillNotFound', 'ExecutionError', 'RepositoryError', 'InternalError']),
    message: z.string(),
    details: z.record(z.any()).optional(),
  });

• src/server.ts:155-193 (registration)

  Registration of invoke_skill as an MCP tool: defines the tool name, description, inputSchema (skill_id required, parameters optional object), outputSchema, and annotations (readOnlyHint: false).

  {
    name: 'invoke_skill',
    description: 'Invoke a skill with parameters to get formatted instructions',
    inputSchema: {
      type: 'object',
      properties: {
        skill_id: {
          type: 'string',
          description: 'Unique identifier of the skill to invoke',
        },
        parameters: {
          type: 'object',
          description: 'Parameters to pass to the skill',
          additionalProperties: true,
        },
      },
      required: ['skill_id'],
    },
    outputSchema: {
      type: 'object',
      properties: {
        success: { type: 'boolean' },
        content: { type: 'string' },
        error: {
          type: 'object',
          properties: {
            code: { type: 'string' },
            message: { type: 'string' },
            details: { type: 'object' },
          },
        },
        executionTime: { type: 'number' },
      },
    },
    annotations: {
      readOnlyHint: false,
      openWorldHint: false,
    },
  },

• src/server.ts:304-337 (handler)

  Handler in the CallToolRequestSchema switch-case that extracts skill_id and parameters from args, validates skill_id presence, delegates to executor.invokeSkill(), and returns the result.

  case 'invoke_skill': {
    const skillId = args?.skill_id as string;
    const parameters = (args?.parameters as Record<string, unknown>) || {};
  
    if (!skillId) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: false,
              error: {
                code: 'InvalidParams',
                message: 'Missing required parameter: skill_id',
              },
            }),
          },
        ],
        isError: true,
      };
    }
  
    const result = await this.executor.invokeSkill(skillId, parameters);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result),
        },
      ],
      isError: !result.success,
    };
  }