Awesome Agent Skills MCP Server

Instructions

Implementation Reference

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

  Main handler for the invoke_skill tool that processes incoming requests, validates the skill_id parameter, calls the executor's invokeSkill method, and returns the formatted response with error handling.

  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,
    };
  }

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

  Core implementation of invokeSkill that checks skill existence, validates parameters using the registry, substitutes parameters into skill content using placeholder replacement ({{param}} and ${param}), and returns a timed success/error result.

  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/server.ts:156-193 (schema)

  Tool schema definition for invoke_skill including input schema (skill_id and parameters), output schema (success, content, error, executionTime), and annotations describing the tool's behavior.

    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/services/skill-executor.ts:69-83 (helper)

  Parameter substitution utility that replaces both {{paramName}} and ${paramName} placeholders in skill content with provided parameter values.

  private substituteParameters(content: string, parameters: Record<string, unknown>): string {
    let result = content;
  
    for (const [key, value] of Object.entries(parameters)) {
      // Replace {{paramName}} placeholders
      const placeholder = new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`, 'g');
      result = result.replace(placeholder, String(value));
  
      // Replace ${paramName} placeholders (alternative syntax)
      const altPlaceholder = new RegExp(`\\$\\{\\s*${key}\\s*\\}`, 'g');
      result = result.replace(altPlaceholder, String(value));
    }
  
    return result;
  }

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

  Type definitions and helper functions for invocation results: InvocationResult type, InvocationError type, createSuccessResult and createErrorResult factory functions used throughout the invoke_skill flow.

  export const invocationErrorSchema = z.object({
    code: z.enum(['InvalidParams', 'SkillNotFound', 'ExecutionError', 'RepositoryError', 'InternalError']),
    message: z.string(),
    details: z.record(z.any()).optional(),
  });
  
  export type InvocationError = z.infer<typeof invocationErrorSchema>;
  
  export const invocationResultSchema = z.object({
    success: z.boolean(),
    content: z.string().optional(),
    error: invocationErrorSchema.optional(),
    executionTime: z.number().int().min(0),
  });
  
  export type InvocationResult = z.infer<typeof invocationResultSchema>;
  
  export function createSuccessResult(content: string, executionTime: number): InvocationResult {
    return {
      success: true,
      content,
      executionTime,
    };
  }
  
  export function createErrorResult(
    code: InvocationError['code'],
    message: string,
    executionTime: number,
    details?: Record<string, unknown>
  ): InvocationResult {
    return {
      success: false,
      error: {
        code,
        message,
        details,
      },
      executionTime,
    };
  }