Related Pages

Related topics: Deployment and Configuration, MCP Server Architecture

Getting Started

The Skill Loader MCP Server is a Model Context Protocol (MCP) server that enables discovery, fetching, validation, and conversion of Claude Skills from the skills.sh marketplace into formats compatible with the Kiro platform. This guide provides everything you need to install, configure, and begin using the server effectively.

Overview

The Skill Loader MCP Server acts as a bridge between the skills.sh marketplace and local skill management systems. It provides a unified interface for:

• Discovering available skills through search and browsing
• Fetching skill content directly from GitHub repositories
• Validating skill content for security issues before import
• Converting skills to Kiro steering file format or power format
• Performing complete end-to-end skill imports with a single command

Sources: README.md:1-10

Architecture Overview

graph TD
    A[Client] -->|MCP Protocol| B[Skill Loader MCP Server]
    B --> C[Skills.sh API]
    B --> D[GitHub Raw Content]
    
    C -->|Search Results| E[list_skills]
    C -->|Trending Data| F[get_leaderboard]
    D -->|Raw .md| G[fetch_skill]
    
    G --> H[validate_skill]
    H -->|Safe| I[convert_to_steering]
    H -->|Safe| J[convert_to_power]
    
    I --> K[Kiro Steering Files]
    J --> L[Kiro Power Format]
    
    G --> M[import_skill]
    M --> H
    M -->|Validated| I
    M -->|Validated| J

Prerequisites

Before installing the Skill Loader MCP Server, ensure your environment meets the following requirements:

Sources: CONTRIBUTING.md:1-5

Installation

Global Installation

For system-wide access, install the package globally using npm:

npm install -g @goldzulu/skill-loader-mcp-server

Sources: README.md:30-32

Local Installation

For project-specific usage, install locally:

npm install @goldzulu/skill-loader-mcp-server

Sources: README.md:34-36

Configuration

Environment Variables

The server uses a single environment variable for authenticated API access:

Sources: README.md:43-47

Configuration with Kiro

Add the server to your Kiro configuration file (mcp.json):

{
  "mcpServers": {
    "skill-loader": {
      "command": "npx",
      "args": ["-y", "@goldzulu/skill-loader-mcp-server"],
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      },
      "description": "Skill Loader MCP Server for managing Claude skills"
    }
  }
}

Sources: README.md:53-64

Configuration with Claude Desktop

For Claude Desktop integration, add to your configuration:

{
  "mcpServers": {
    "skill-loader": {
      "command": "skill-loader-mcp-server",
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Sources: README.md:70-80

Available Tools

The server provides eight MCP tools for skill management. Each tool accepts JSON-formatted arguments and returns structured responses.

Sources: README.md:82-100

Tool Overview

Sources: README.md:82-100

1. search_skills

Search for skills by keyword using the skills.sh public search API. No authentication required.

Parameters:

Example Request:

{
  "tool": "search_skills",
  "arguments": {
    "query": "pdf",
    "limit": 5
  }
}

Example Response:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400,
      "relevance": 5
    }
  ],
  "query": "pdf",
  "count": 5
}

Sources: examples/usage-examples.md:1-50

2. list_skills

List all available skills from skills.sh with pagination. Requires SKILLS_SH_API_KEY.

Parameters:

Example Request:

{
  "tool": "list_skills",
  "arguments": {
    "page": 1,
    "pageSize": 10
  }
}

Sources: README.md:102-115

3. get_leaderboard

Get trending or top-installed skills. Requires SKILLS_SH_API_KEY.

Parameters:

Example Request:

{
  "tool": "get_leaderboard",
  "arguments": {
    "timeframe": "24h",
    "limit": 10
  }
}

Example Response:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400,
      "rank": 1,
      "trending": true
    }
  ],
  "timeframe": "24h",
  "count": 10
}

Sources: examples/usage-examples.md:90-120

4. fetch_skill

Fetch raw skill content directly from GitHub. Supports both simple skill names and owner/repo format.

Parameters:

Example Request:

{
  "tool": "fetch_skill",
  "arguments": {
    "identifier": "anthropics/pdf-extractor"
  }
}

Example Response:

{
  "content": "---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\n...",
  "url": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md",
  "metadata": {
    "name": "pdf-extractor",
    "owner": "anthropics",
    "repo": "skills",
    "skillPath": "skills/pdf-extractor",
    "fetchedAt": "2024-01-15T10:30:00.000Z"
  }
}

Sources: examples/usage-examples.md:130-165

5. validate_skill

Validate skill content for security issues before importing. This tool scans for dangerous commands, suspicious patterns, and untrusted sources.

Parameters:

Example Request:

{
  "tool": "validate_skill",
  "arguments": {
    "content": "---\nname: Test\n---\n\n# Test",
    "url": "https://example.com/skill.md"
  }
}

Security Checks Performed:

Sources: README.md:155-175

Severity Levels:

Sources: src/core/security-validator.ts:1-30

6. convert_to_steering

Convert skill content to Kiro steering file format. This format adds metadata headers and preserves the original skill structure.

Parameters:

Example Request:

{
  "tool": "convert_to_steering",
  "arguments": {
    "content": "---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\nExtract text content from PDF documents.",
    "sourceUrl": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md"
  }
}

Sources: examples/usage-examples.md:195-220

7. convert_to_power

Convert skill to Kiro power format. This generates additional configuration files based on skill complexity:

• mcp.json: Generated when the skill has dependencies or MCP server references
• steering/ directory: Generated when the skill has 3+ complex sections

Parameters:

Example Request:

{
  "tool": "convert_to_power",
  "arguments": {
    "content": "---\nname: Test\ndescription: A test skill\n---\n\n# Test",
    "sourceUrl": "https://example.com/skill.md"
  }
}

Sources: README.md:190-205

8. import_skill

Complete import workflow combining fetch, validate, and convert operations in a single command.

Parameters:

Example Request (Steering Format):

{
  "tool": "import_skill",
  "arguments": {
    "identifier": "anthropics/pdf-extractor",
    "outputFormat": "steering"
  }
}

Example Response:

{
  "success": true,
  "content": "---\noriginal_skill: PDF Extractor\nsource_url: https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md\nimported_at: '2024-01-15T10:30:00.000Z'\n---\n\n...",
  "filename": "pdf-extractor.md",
  "targetPath": ".kiro/steering/pdf-extractor.md",
  "metadata": {
    "skillName": "PDF Extractor",
    "sourceUrl": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md",
    "outputFormat": "steering",
    "validationResult": {
      "isValid": true,
      "issues": [],
      "severity": "safe"
    }
  }
}

Sources: examples/usage-examples.md:250-280

Common Workflows

Discovery and Import Workflow

graph LR
    A[Search Skills] --> B[Find Interesting Skill]
    B --> C[Fetch Skill]
    C --> D{Validate}
    D -->|Issues Found| E[Review Security Issues]
    D -->|Safe| F[Choose Format]
    E -->|Override| F
    F --> G[Import as Steering]
    F --> H[Import as Power]

Quick Start: Discover and Import

1. Search for skills by keyword:

{ "tool": "search_skills", "arguments": { "query": "pdf", "limit": 20 } }

1. Import a trending skill:

{ "tool": "import_skill", "arguments": { "identifier": "owner/skill-name", "outputFormat": "power" } }

Validate Before Importing

1. Fetch the skill:

{ "tool": "fetch_skill", "arguments": { "identifier": "unknown/skill" } }

1. Validate the content:

{ "tool": "validate_skill", "arguments": { "content": "...", "url": "..." } }

1. If safe, convert and use:

{ "tool": "convert_to_steering", "arguments": { "content": "...", "sourceUrl": "..." } }

Sources: examples/usage-examples.md:330-360

Caching

The server implements in-memory caching for skills.sh search results to reduce API calls and improve performance.

Sources: README.md:180-182

Error Handling

All tools return errors in a consistent format:

{
  "error": "Error message describing what went wrong",
  "tool": "tool_name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Common Error Scenarios

Sources: examples/usage-examples.md:365-375

Development Setup

For local development and contribution:

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Sources: CONTRIBUTING.md:8-14

Project Structure

skill-loader-mcp-server/
├── src/
│   ├── core/           # Core functionality
│   │   ├── conversion-engine.ts
│   │   ├── security-validator.ts
│   │   └── errors.ts
│   ├── tools/          # MCP tool implementations
│   ├── utils/          # Utility functions
│   ├── index.ts        # Main entry point
│   └── cli.ts          # CLI entry point
├── examples/           # Usage examples
├── dist/               # Compiled output
└── tests/              # Test files

Sources: CONTRIBUTING.md:16-28

Supported Versions

Sources: CHANGELOG.md:1-10

Next Steps

• Review the Usage Examples for detailed tool demonstrations
• Check the CONTRIBUTING.md if you wish to contribute to the project
• Explore the CHANGELOG.md for version history and recent changes

Related Pages

Related topics: Getting Started, Core Modules

Project Structure

The skill-loader-mcp-server is a Model Context Protocol (MCP) server that enables discovery, fetching, validation, and conversion of Claude skills from the skills.sh marketplace. The project follows a modular architecture with clear separation between core functionality, MCP tool implementations, and utility modules.

Architecture Overview

The server is built on the @modelcontextprotocol/sdk framework and exposes 9 MCP tools for skill management operations. The architecture follows a layered pattern where the core layer handles business logic, the tools layer exposes MCP-compatible interfaces, and the utils layer provides shared functionality.

graph TD
    A[Client] --> B[MCP Server Entry]
    B --> C[Tool Handlers]
    C --> D[Core Services]
    C --> E[SkillResolver]
    C --> F[ConversionEngine]
    C --> G[SecurityValidator]
    D --> H[skills.sh API]
    D --> I[GitHub API]
    G --> J[Error System]

Directory Structure

skill-loader-mcp-server/
├── src/
│   ├── core/           # Core business logic
│   ├── tools/          # MCP tool implementations
│   ├── utils/          # Utility functions
│   ├── index.ts        # Main entry point
│   └── cli.ts          # CLI entry point
├── examples/           # Usage examples
├── dist/               # Compiled output
├── tests/              # Test files
├── package.json
└── tsconfig.json

Source Directory Organization

The src/ directory contains the primary application code organized into functional layers:

Entry Points

The project provides two entry points for different execution contexts.

Main Entry Point (index.ts)

The primary entry point initializes the MCP server with stdio transport and registers all available tools. This is the standard entry used when the server runs as an MCP server integration.

// Conceptual structure from src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'skill-loader', version: '1.1.0' },
  { capabilities: { tools: {} } }
);

// Register tools and start transport
const transport = new StdioServerTransport();
await server.connect(transport);

Sources: CONTRIBUTING.md:23-24

CLI Entry Point (cli.ts)

The CLI entry point provides standalone execution capability, allowing the server to run as a command-line utility. This is useful for direct invocation and debugging scenarios.

Sources: CONTRIBUTING.md:19

Core Layer Modules

Conversion Engine

The conversion engine (src/core/conversion-engine.ts) handles transformation of skills between different formats. It supports conversion to steering files and power formats with additional generation capabilities.

Key Responsibilities:

• Parse YAML frontmatter and markdown body from skill content
• Convert to Kiro steering file format with metadata preservation
• Generate POWER.md content with dependencies section
• Create mcp.json for skills with dependencies or tool references
• Generate steering/ directory for skills with multiple complex sections
• Extract keywords from descriptions for metadata

Conversion Output Formats:

Sources: src/core/conversion-engine.ts:1-200

Security Validator

The security validator (src/core/security-validator.ts) scans skill content for potential security threats before import. It provides a consistent validation interface across all import operations.

Security Checks Performed:

Severity Levels:

• safe: No issues detected
• warning: Suspicious patterns found, import allowed
• unsafe: Dangerous patterns detected, import blocked

Sources: src/core/security-validator.ts:1-100

Error Handling System

The error system (src/core/errors.ts) provides structured error types with recovery suggestions. All errors extend a base SkillLoaderError class with context tracking.

Error Hierarchy:

Sources: src/core/errors.ts:1-150

Tool Layer

The tools layer implements MCP-compatible handlers that expose core functionality to MCP clients. Each tool follows a consistent pattern of parameter validation, execution, and response formatting.

Available MCP Tools

Sources: README.md:40-120

Data Flow

sequenceDiagram
    participant Client
    participant Server
    participant Resolver
    participant Validator
    participant Converter
    participant External

    Client->>Server: import_skill(identifier, format)
    Server->>Resolver: fetchSkill(identifier)
    Resolver->>External: GET GitHub raw content
    External-->>Resolver: SKILL.md content
    Resolver-->>Server: rawContent
    Server->>Validator: validate(content, url)
    Validator-->>Server: ValidationResult
    Server->>Converter: convert(content, format, url)
    Converter-->>Server: ConvertResult
    Server-->>Client: ImportResult

    alt skipValidation = true
        Server->>Converter: Skip validation
    end

Module Dependencies

graph TD
    A[index.ts] --> B[tools/*]
    B --> C[core/ConversionEngine]
    B --> D[core/SkillResolver]
    B --> E[core/SecurityValidator]
    C --> F[core/errors.ts]
    D --> F
    E --> F
    C --> G[utils/*]
    D --> G

Configuration

Environment Variables

Sources: README.md:28-35

TypeScript Configuration

The project uses TypeScript with strict mode enabled. Key configuration in tsconfig.json:

• ES2022 target for modern JavaScript features
• ES modules (module: nodenext)
• Strict type checking enabled
• Path aliases for clean imports

Sources: tsconfig.json

Build and Deployment

Build Process

# Install dependencies
npm install

# Build TypeScript
npm run build

# Output to dist/ directory

Deployment Targets

Sources: README.md:20-55

Testing Structure

The tests/ directory follows the project structure with test files mirroring source file organization. Tests use descriptive naming and follow the pattern:

tests/
├── core/
│   ├── conversion-engine.test.ts
│   ├── security-validator.test.ts
│   └── errors.test.ts
└── tools/
    └── *.test.ts

Sources: CONTRIBUTING.md:80-100

Summary

The project architecture emphasizes separation of concerns with a clear hierarchy from entry points through tool handlers to core services. The core layer is framework-agnostic and handles all business logic including skill fetching, validation, and conversion. The tools layer provides MCP-compatible interfaces while delegating to core services. This design allows for easy testing, maintainability, and extension of new features.

Related Pages

Related topics: MCP Tools Reference, Getting Started

MCP Server Architecture

The Skill Loader MCP Server is a Model Context Protocol (MCP) server implementation that enables AI assistants to discover, fetch, validate, and import Claude skills from the skills.sh marketplace. Built on the @modelcontextprotocol/sdk, it provides a comprehensive toolset for skill management with enterprise-grade security validation.

Architecture Overview

The server follows a layered architecture pattern with clear separation between the transport layer, tool handlers, core services, and utilities.

graph TD
    subgraph Transport Layer
        STDIO[Stdio Transport]
        HTTP[HTTP/SSE Transport]
    end

    subgraph MCP SDK
        Server[MCP Server Instance]
        Handlers[Request Handlers]
    end

    subgraph Core Services
        SR[SkillResolver]
        SV[SecurityValidator]
        CE[ConversionEngine]
        Cache[In-Memory Cache]
    end

    subgraph External Services
        SkillsAPI[skills.sh API]
        GitHub[GitHub API]
    end

    STDIO --> Server
    HTTP --> Server
    Server --> Handlers
    Handlers --> SR
    Handlers --> SV
    Handlers --> CE
    SR --> Cache
    SR --> SkillsAPI
    SR --> GitHub
    CE --> SV

Core Components

Server Initialization

The server is initialized with the @modelcontextprotocol/sdk version 1.29 and configured with stdio transport for maximum compatibility.

// Simplified initialization pattern
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "skill-loader", version: "1.x.x" },
  { capabilities: { tools: {} } }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Sources: README.md:1-50

The server supports both stdio transport (for CLI and desktop integrations) and can be configured for HTTP/SSE transport when deployed as a network service.

Tool System

The server exposes 8 MCP tools that provide complete skill management capabilities:

Tool Overview

Sources: README.md:50-120

Tool Request Flow

sequence diagram
    participant Client
    participant Server
    participant Resolver
    participant Validator
    participant Converter

    Client->>Server: tool_request
    Server->>Resolver: fetch/resolve skill
    Resolver-->>Server: raw content
    Server->>Validator: scan content
    alt Validation Failed
        Server-->>Client: error with issues
    else Validation Passed
        Server->>Converter: transform content
        Converter-->>Server: formatted output
    end
    Server-->>Client: tool_response

Core Services

SkillResolver

The SkillResolver service handles all interactions with external skill sources. It provides:

• GitHub Resolution: Parse owner/repo identifiers to fetch raw skill content
• skills.sh API Integration: Query marketplace for search, listing, and leaderboard
• Content Fetching: Retrieve raw SKILL.md files from GitHub repositories

interface ISkillResolver {
  resolveGitHub(identifier: string): Promise<SkillContent>;
  searchSkills(query: string, limit: number): Promise<SearchResult[]>;
  listSkills(page: number, pageSize: number): Promise<PaginatedResult>;
  getLeaderboard(timeframe: string, limit: number): Promise<LeaderboardEntry[]>;
}

Sources: src/core/conversion-engine.ts:1-50

The resolver supports the skills.sh API v1 responses with types including SkillsShV1Response, SkillsShV1Entry, and extends SkillShEntry with additional fields like id, skillId, and source.

SecurityValidator

The SecurityValidator service performs comprehensive security scanning on skill content before import.

interface ValidationIssue {
  type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source';
  description: string;
  severity: 'critical' | 'warning' | 'info';
  lineNumber?: number;
  location?: string;
}

Sources: src/core/security-validator.ts:1-80

#### Security Checks Performed

#### Severity Determination

The validator calculates overall severity based on detected issues:

• Safe: No issues found
• Warning: Only suspicious patterns detected
• Unsafe: Dangerous commands or untrusted sources present

Sources: src/core/security-validator.ts:80-100

ConversionEngine

The ConversionEngine transforms Claude skills into Kiro-compatible formats. It supports two output formats:

#### Steering Format

Converts skills to Kiro steering file format:

• Preserves skill body content
• Adds YAML frontmatter with original skill metadata
• Includes dependencies section if present
• Adds import attribution footer

interface SteeringOutput {
  filename: string;        // kebab-case derived from skill name
  content: string;         // Full steering file content
  metadata: {
    originalSkill: string;
    sourceUrl?: string;
    importedAt: string;     // ISO timestamp
  };
}

Sources: src/core/conversion-engine.ts:50-150

#### Power Format

Converts skills to Kiro power format with enhanced capabilities:

• POWER.md: Primary power definition file
• mcp.json (optional): Generated when skill has dependencies or MCP server references
• steering/ directory (optional): Generated for skills with 3+ complex sections

interface PowerOutput {
  filename: string;         // "POWER.md"
  content: string;          // Power content with metadata
  files?: Array<{
    path: string;
    content: string;
  }>;
}

Sources: src/core/conversion-engine.ts:150-250

#### Format Selection Logic

Sources: src/core/conversion-engine.ts:250-300

Error Handling System

The server implements a hierarchical error system with specialized error classes for different failure modes.

graph TD
    SkillLoaderError[SkillLoaderError]
    NetworkError[NetworkError]
    ValidationError[ValidationError]
    FileSystemError[FileSystemError]
    SkillLoaderError --> NetworkError
    SkillLoaderError --> ValidationError
    SkillLoaderError --> FileSystemError

Error Class Hierarchy

Sources: src/core/errors.ts:1-100

Error Response Format

{
  "error": "Error message describing what went wrong",
  "tool": "tool_name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

All errors include recovery suggestions based on error type and context.

Caching Mechanism

The server implements in-memory caching for the skills.sh directory to reduce API calls and improve performance.

Sources: README.md:180-200

Cache invalidation is automatic when the TTL expires. No manual cache clearing is required.

Configuration and Deployment

Environment Variables

Deployment Targets

graph LR
    subgraph Deployment Options
        Kiro[Kiro MCP Config]
        Claude[Claude Desktop]
        CLI[Standalone CLI]
    end

    Kiro --> STDIO
    Claude --> STDIO
    CLI --> STDIO

#### Kiro Configuration

{
  "mcpServers": {
    "skill-loader": {
      "command": "npx",
      "args": ["-y", "@goldzulu/skill-loader-mcp-server"],
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

#### Claude Desktop Configuration

{
  "mcpServers": {
    "skill-loader": {
      "command": "skill-loader-mcp-server",
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Sources: README.md:30-80

Project Structure

skill-loader-mcp-server/
├── src/
│   ├── core/               # Core business logic
│   │   ├── conversion-engine.ts
│   │   ├── errors.ts
│   │   └── security-validator.ts
│   ├── tools/              # MCP tool implementations
│   ├── utils/              # Utility functions
│   ├── index.ts            # Server entry point
│   └── cli.ts              # CLI entry point
├── examples/               # Usage examples
├── tests/                  # Test suite
├── dist/                   # Compiled output
├── package.json
└── tsconfig.json

Sources: CONTRIBUTING.md:1-30

Dependencies

The server relies on the following key dependencies:

Sources: package.json

Complete Import Workflow

graph TD
    A[Start: identifier] --> B[Fetch Skill from GitHub]
    B --> C{skipValidation?}
    C -->|No| D[Security Validation]
    C -->|Yes| E[Skip Validation]
    D --> F{isValid?}
    F -->|No| G[Return Error with Issues]
    F -->|Yes| E
    E --> H{outputFormat?}
    H -->|steering| I[Convert to Steering]
    H -->|power| J[Convert to Power]
    I --> K[Add Steering Metadata]
    J --> L[Generate Power Files]
    L --> M{mcp.json needed?}
    L --> N{steering/ needed?}
    M -->|Yes| O[Generate mcp.json]
    M -->|No| P[Skip mcp.json]
    N -->|Yes| Q[Generate steering/]
    N -->|No| R[Skip steering/]
    O --> S[Return Result]
    P --> S
    Q --> S
    R --> S

The complete workflow is exposed through the import_skill tool, which orchestrates fetch, validation, and conversion in a single operation.

Sources: examples/usage-examples.md:100-150

Version History

Sources: CHANGELOG.md

Related Pages

Related topics: Format Conversion, Security Validation

Core Modules

The Core Modules of the skill-loader-mcp-server form the foundational layer responsible for skill fetching, parsing, security validation, and format conversion. These modules work together to provide a secure pipeline for importing Claude skills into the Kiro ecosystem.

Architecture Overview

graph TD
    A[Skill Input] --> B[Skill Fetcher]
    B --> C[Skill Resolver]
    C --> D[Conversion Engine]
    D --> E[Steering Format]
    D --> F[Power Format]
    G[Security Validator] --> D
    G --> C
    H[Error Handler] --> B
    H --> C
    H --> D
    H --> G

Module Components

1. Conversion Engine (`conversion-engine.ts`)

The Conversion Engine is responsible for transforming parsed skill content into different output formats suitable for various use cases.

#### Key Methods

#### Steering File Conversion

The steering file format preserves the original skill structure with kebab-case naming:

// Transformation rules:
// 1. Convert to lowercase
// 2. Replace spaces and underscores with hyphens
// 3. Remove special characters (keep only a-z, 0-9, and hyphens)
// 4. Collapse multiple consecutive hyphens into one
// 5. Remove leading and trailing hyphens

"PDF Extractor" → "pdf-extractor"
"React_Best_Practices" → "react-best-practices"

Sources: src/core/conversion-engine.ts:1-50

#### Power Format Generation

The power format generates a more structured output:

// Power structure includes:
// 1. POWER.md - Main content with displayName frontmatter
// 2. mcp.json - (optional) MCP server configuration
// 3. steering/ - (optional) Directory with complex sections

Sources: src/core/conversion-engine.ts:150-200

#### Steering Directory Generation Logic

The engine generates a steering/ directory when the skill has 3+ complex sections (level ≥ 2 with content > 200 characters):

if (this.shouldGenerateSteeringDir(skill)) {
  const steeringContent = this.generateSteeringContent(skill);
  // Creates individual files for each complex section
}

Sources: src/core/conversion-engine.test.ts:1-50

Related Pages

Related topics: MCP Server Architecture, Skill Discovery

MCP Tools Reference

The Skill Loader MCP Server provides a comprehensive suite of 8 Model Context Protocol (MCP) tools for discovering, fetching, validating, and converting Claude skills from the skills.sh marketplace. These tools enable seamless integration between the skills.sh ecosystem and the Kiro AI platform's steering file and power formats.

Overview

The MCP Tools form the core interface of the Skill Loader MCP Server, providing programmatic access to the skills.sh API and GitHub-hosted skill repositories. Each tool serves a specific purpose in the skill management lifecycle, from discovery to import.

graph TD
    A[Skills Discovery] --> B[search_skills]
    A --> C[list_skills]
    A --> D[get_leaderboard]
    E[Skill Retrieval] --> F[fetch_skill]
    G[Security] --> H[validate_skill]
    I[Conversion] --> J[convert_to_steering]
    I --> K[convert_to_power]
    L[Workflow] --> M[import_skill]
    
    F --> H
    H --> J
    H --> K
    M --> F
    M --> H
    M --> J
    M --> K

Tool Categories

Sources: README.md

Discovery Tools

search_skills

Search for skills by keyword using the skills.sh search API. This tool requires no authentication and provides immediate access to the skill marketplace.

Parameters:

Response Schema:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400,
      "relevance": 5
    }
  ],
  "query": "pdf",
  "count": 5
}

Example Request:

{
  "tool": "search_skills",
  "arguments": {
    "query": "pdf",
    "limit": 5
  }
}

Sources: examples/usage-examples.md

list_skills

List all available skills from skills.sh with pagination support. This tool requires the SKILLS_SH_API_KEY environment variable for authenticated access to the paginated directory endpoint.

Parameters:

Response Schema:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400
    }
  ],
  "total": 150,
  "page": 1,
  "pageSize": 10
}

Authentication Requirement:

This tool requires SKILLS_SH_API_KEY to access the authenticated /api/v1/skills endpoint. Request the API key from Vercel if needed.

Sources: README.md

get_leaderboard

Get trending or top-installed skills to identify the most popular skills in the marketplace.

Parameters:

Response Schema:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400,
      "rank": 1,
      "trending": true
    }
  ],
  "timeframe": "24h",
  "count": 10
}

Authentication Requirement:

Similar to list_skills, this tool requires SKILLS_SH_API_KEY for authenticated access.

Sources: examples/usage-examples.md

Retrieval Tools

fetch_skill

Fetch raw skill content directly from GitHub. This tool supports both short identifiers (skill name) and fully-qualified identifiers (owner/repo format).

graph TD
    A[fetch_skill Request] --> B{Identifier Format?}
    B -->|Short name| C[Query skills.sh directory]
    B -->|owner/repo| D[Direct GitHub URL construction]
    C --> E[Resolve to owner/repo]
    E --> F[Construct GitHub URL]
    D --> F
    F --> G[Fetch from GitHub Raw]
    G --> H[Return Skill Content]
    
    H --> I[Extract YAML frontmatter]
    H --> J[Parse markdown body]
    H --> K[Extract sections]

Parameters:

Supported Identifier Formats:

Response Schema:

{
  "content": "---\nname: PDF Extractor\ndescription: Extract text from PDF files\n---\n\n# PDF Extractor\n\n...",
  "url": "https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf-extractor/SKILL.md",
  "metadata": {
    "name": "pdf-extractor",
    "owner": "anthropics",
    "repo": "skills",
    "skillPath": "skills/pdf-extractor",
    "fetchedAt": "2024-01-15T10:30:00.000Z"
  }
}

URL Resolution Pattern:

The SkillResolver class constructs URLs using the pattern:

https://raw.githubusercontent.com/{owner}/{repo}/main/skills/{name}/SKILL.md

Sources: src/core/skill-resolver.ts

Security Tools

validate_skill

Validate skill content for security issues before importing. This is a critical security measure that scans for dangerous commands, suspicious patterns, and code injection vulnerabilities.

graph TD
    A[Skill Content] --> B[SecurityValidator]
    B --> C{Dangerous Commands?}
    B --> D{Suspicious Patterns?}
    B --> E{Untrusted Sources?}
    
    C -->|rm -rf, sudo, eval| F[dangerous_command]
    D -->|Code injection, special chars| G[suspicious_pattern]
    E -->|Non-GitHub URLs| H[untrusted_source]
    
    F --> I{Severity Assessment}
    G --> I
    H --> I
    I --> J[Validation Result]
    
    J --> K{Result}
    K -->|No issues| L["severity: safe"]
    K -->|Untrusted/Dangerous| M["severity: unsafe"]
    K -->|Suspicious only| N["severity: warning"]

Parameters:

Detected Security Issues:

Dangerous Patterns Scanned:

• Recursive delete commands (rm -rf)
• Privilege escalation (sudo)
• Dynamic code execution (eval, exec)
• Path traversal attempts (/etc/, /usr/, /bin/)
• Shell interpolation patterns (${, $()

Response Schema:

{
  "isValid": false,
  "issues": [
    {
      "type": "dangerous_command",
      "description": "Dangerous recursive delete command (rm -rf)",
      "location": "Line 7: rm -rf /"
    }
  ],
  "severity": "unsafe"
}

Severity Determination Logic:

Sources: src/core/security-validator.ts

Conversion Tools

convert_to_steering

Convert skill content to Kiro steering file format. This format is designed for guiding AI behavior through structured markdown with YAML frontmatter.

Parameters:

Output Format Structure:

Related Pages

Related topics: MCP Tools Reference, Caching System

Skill Discovery

Skill Discovery is a core subsystem of the Skill Loader MCP Server that enables users to find, browse, and explore available Claude skills from the skills.sh ecosystem. It provides multiple discovery mechanisms including keyword search, paginated listing, and trending leaderboards.

Overview

The Skill Discovery system acts as the front-end interface for exploring the skills.sh marketplace. It abstracts away the complexity of fetching and filtering skills from external APIs, providing a unified interface for skill exploration.

Key Capabilities

• Keyword Search: Find skills by name or description keywords
• Paginated Listing: Browse all available skills with pagination support
• Trending Leaderboard: Discover popular or recently trending skills
• Source Resolution: Resolve skill identifiers to GitHub URLs
• Install Statistics: View install counts for skill popularity metrics

Architecture Overview

graph TD
    A[User Request] --> B[MCP Tools Layer]
    B --> C[search_skills]
    B --> D[list_skills]
    B --> E[get_leaderboard]
    C --> F[SkillResolver]
    D --> F
    E --> F
    F --> G[Skills.sh API]
    F --> H[GitHub Raw Content]
    G --> I[SkillShEntry Parser]
    I --> J[ResolvedSkill Output]
    H --> J

Core Components

SkillResolver

The SkillResolver class is the central orchestrator for skill discovery operations. Located at src/core/skill-resolver.ts, it handles all interactions with the skills.sh API and provides unified resolution of skill identifiers.

Primary Methods:

Sources: src/core/skill-resolver.ts:1-50

Data Models

#### SkillShEntry

Represents a skill entry from the skills.sh API:

interface SkillShEntry {
  name: string;
  owner: string;
  repo: string;
  installs: number;
  description: string;
  id?: string;
  skillId?: string;
  source?: string;
  metadata?: {
    trending: boolean;
  };
}

#### ResolvedSkill

Internal representation after resolution:

interface ResolvedSkill {
  name: string;
  description: string;
  owner: string;
  repo: string;
  skillPath: string;
  url: string;
  installs: number;
}

Sources: src/core/skill-resolver.ts:60-100

Discovery Tools

1. search_skills

Performs keyword-based search across skill names and descriptions. This tool uses the public search API endpoint and does not require authentication.

Parameters:

Workflow:

graph LR
    A[query: string] --> B[Call skills.sh Search API]
    B --> C[Parse Response]
    C --> D[Filter by Relevance]
    D --> E[Return Top N Results]
    E --> F[Skills with relevance scores]

Response Structure:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400,
      "relevance": 5
    }
  ],
  "query": "pdf",
  "count": 5
}

Sources: examples/usage-examples.md:30-60

2. list_skills

Retrieves a paginated list of all available skills from the skills.sh directory. Requires SKILLS_SH_API_KEY for authenticated access to the v1 API endpoint.

Parameters:

API Integration:

const url = `https://skills.sh/api/v1/skills?page=${page}&pageSize=${pageSize}`;
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

Response Structure:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400
    }
  ],
  "total": 150,
  "page": 1,
  "pageSize": 10
}

Sources: examples/usage-examples.md:20-40

3. get_leaderboard

Retrieves trending or top-installed skills ranked by popularity metrics.

Parameters:

Timeframe Behavior:

Response Structure:

{
  "skills": [
    {
      "name": "pdf-extractor",
      "description": "Extract text from PDF files",
      "owner": "anthropics",
      "repo": "skills",
      "installs": 30400,
      "rank": 1,
      "trending": true
    }
  ],
  "timeframe": "24h",
  "count": 10
}

Sources: examples/usage-examples.md:55-80

Skill Resolution Flow

The resolution process transforms various identifier formats into canonical GitHub URLs:

graph TD
    A[Identifier Input] --> B{Normalize Identifier}
    B --> C["owner/repo format?"]
    C -->|Yes| D[Build URL: owner/repo]
    C -->|No| E[Search skills.sh Directory]
    E --> F{Match Found?}
    F -->|Single| G[Use Match]
    F -->|Multiple| H[Raise Error: Multiple Matches]
    F -->|None| I[Raise Error: Not Found]
    D --> J[Build Full GitHub URL]
    G --> J
    J --> K[Return ResolvedSkill]

Resolution Rules

1. Explicit Format (owner/repo): Directly constructs GitHub URL
2. Name Only: Searches skills.sh directory for matching name
3. Fuzzy Match: Case-insensitive partial matching on skill names
4. Multiple Matches: Throws SkillResolutionError with list of matches

Sources: src/core/skill-resolver.ts:100-150

API Integration

Skills.sh API Endpoints

Authentication

const response = await fetch(url, {
  headers: {
    'Authorization': `Bearer ${process.env.SKILLS_SH_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

Error Handling

Sources: src/core/skill-resolver.ts:150-200

Caching Strategy

The Skill Discovery system implements in-memory caching for the skills.sh directory to reduce API calls and improve performance.

graph LR
    A[Request] --> B{Cache Valid?}
    B -->|Yes| C[Return Cached Data]
    B -->|No| D[Fetch from API]
    D --> E[Update Cache]
    E --> F[Return Fresh Data]
    C --> G[Response]
    F --> G

Cache Configuration:

Sources: examples/usage-examples.md:150-160

Usage Examples

Discover Skills by Keyword

{
  "tool": "search_skills",
  "arguments": {
    "query": "pdf",
    "limit": 5
  }
}

Browse Available Skills

{
  "tool": "list_skills",
  "arguments": {
    "page": 1,
    "pageSize": 10
  }
}

Find Trending Skills

{
  "tool": "get_leaderboard",
  "arguments": {
    "timeframe": "24h",
    "limit": 20
  }
}

Complete Discovery Workflow

graph TD
    A[Search for Skills] --> B[Found Interesting Skill?]
    B -->|Yes| C[Fetch Skill Details]
    B -->|No| A
    C --> D[Validate Skill Content]
    D --> E{Valid?}
    E -->|Yes| F[Convert to Target Format]
    E -->|No| G[Review Security Issues]
    G --> H[Skip or Find Alternative]
    F --> I[Import Skill]
    I --> J[Complete]

Sources: examples/usage-examples.md:170-210

Related Systems

Conversion Engine Integration

After discovery, skills can be converted to target formats:

Security Validation

All discovered skills should be validated before import using the validate_skill tool to scan for:

• Dangerous commands (rm -rf, sudo, eval)
• Suspicious file operations (/etc/, /usr/)
• Code injection patterns (${...}, $(...))

Sources: src/core/security-validator.ts:1-50

Summary

Skill Discovery provides the foundational capability to explore and find Claude skills from the skills.sh ecosystem. Through a combination of search, listing, and trending endpoints, users can efficiently discover relevant skills for their needs. The system emphasizes:

• Performance: In-memory caching with 1-hour TTL
• Reliability: Retry logic with exponential backoff
• Security: Integration with validation pipeline
• Developer Experience: Clear error messages with actionable suggestions

For implementation details, refer to the source files listed at the beginning of this page.

Related Pages

Related topics: Error Handling, Format Conversion

Security Validation

The Security Validation system is a critical component of the Skill Loader MCP Server that protects users from potentially malicious or unsafe skill content. It performs comprehensive static analysis on skill markdown files before they are imported, converted, or executed.

Overview

The security validation module (SecurityValidator) scans skill content for multiple categories of security threats, including dangerous system commands, file system access patterns, code injection vulnerabilities, and untrusted content sources. Skills that fail security validation are blocked from import unless validation is explicitly skipped.

Purpose:

• Prevent execution of harmful system commands
• Block imports from non-verified sources
• Detect potential code injection patterns
• Protect the host system from malicious skills

Scope: All skill content passing through the server's import, validation, and conversion workflows.

Sources: src/core/security-validator.ts:1-50

Architecture

graph TD
    A[Skill Content Input] --> B[SecurityValidator.validate]
    B --> C{Dangerous Commands?}
    C -->|Yes| D[Issue: dangerous_command]
    B --> E{Suspicious File Ops?}
    E -->|Yes| F[Issue: suspicious_file_operation]
    B --> G{Code Injection?}
    G -->|Yes| H[Issue: code_injection]
    B --> I{Untrusted Source?}
    I -->|Yes| J[Issue: untrusted_source]
    B --> K{Suspicious Patterns?}
    K -->|Yes| L[Issue: suspicious_pattern]
    
    D --> M[ValidationResult.issues]
    F --> M
    H --> M
    J --> M
    L --> M
    
    M --> N[getSeverity]
    N --> O{hasDangerousCommand<br/>or untrustedSource?}
    O -->|Yes| P[Severity: unsafe]
    N --> Q{hasIssues?}
    Q -->|Yes| R[Severity: warning]
    N --> S{noIssues?}
    S -->|Yes| T[Severity: safe]

Validation Checks

The security validator performs five distinct categories of checks:

1. Dangerous Commands

Detects execution of potentially harmful shell commands that could damage the system.

Sources: src/core/security-validator.ts:60-80

Example detected content:

rm -rf /
sudo rm -rf /usr
eval $user_input
exec sh

2. Suspicious File Operations

Identifies attempts to access or modify sensitive system directories.

Sources: src/core/security-validator.ts:81-100

3. Code Injection Patterns

Detects template injection and command substitution vulnerabilities.

Sources: src/core/security-validator.ts:101-120

Example detected content:

echo ${MALICIOUS_VAR}
Result: $(whoami)

4. Untrusted Sources

Blocks content from non-GitHub sources that cannot be verified.

Sources: src/core/security-validator.ts:121-140

5. Suspicious Patterns

Flags potentially concerning patterns that warrant review.

Sources: src/core/security-validator.ts:141-160

Data Models

ValidationIssue

interface ValidationIssue {
  type: 'dangerous_command' | 'suspicious_file_operation' | 
        'code_injection' | 'untrusted_source' | 'suspicious_pattern';
  description: string;
  line: number;
  content: string;
}

Sources: src/core/security-validator.ts:20-30

ValidationResult

interface ValidationResult {
  isValid: boolean;
  issues: ValidationIssue[];
  severity: 'safe' | 'warning' | 'unsafe';
}

Sources: src/core/security-validator.ts:31-45

Severity Calculation

The severity determination follows a hierarchical logic:

graph LR
    A[Issues Array] --> B{Contains<br/>dangerous_command<br/>or untrusted_source?}
    B -->|Yes| C[unsafe]
    B -->|No| D{Has any<br/>issues?}
    D -->|Yes| E[warning]
    D -->|No| F[safe]

Sources: src/core/security-validator.ts:170-190

Integration Points

The security validator is integrated into the skill import workflow at multiple stages:

graph TD
    A[import_skill Tool] --> B[fetch_skill]
    B --> C{validate_skill}
    C --> D{skipValidation?}
    D -->|No| E[SecurityValidator.validate]
    D -->|Yes| F[Skip validation]
    E --> G{unsafe?}
    G -->|Yes| H[Block import<br/>Return error]
    G -->|No| I[Proceed]
    F --> I
    I --> J[convert_to_steering<br/>or convert_to_power]
    J --> K[Import complete]

validate_skill Tool

The validate_skill MCP tool provides standalone security validation:

Parameters:

Example Request:

{
  "tool": "validate_skill",
  "arguments": {
    "content": "---\nname: Test\n---\n\n# Test",
    "url": "https://github.com/example/repo/main/skill.md"
  }
}

Example Response:

{
  "isValid": false,
  "issues": [
    {
      "type": "dangerous_command",
      "description": "Dangerous recursive delete command (rm -rf)",
      "location": "Line 7: rm -rf /"
    }
  ],
  "severity": "unsafe"
}

Sources: src/tools/validate-skill.ts

Error Handling

Validation errors are wrapped in the ValidationError class for consistent error handling:

export class ValidationError extends SkillLoaderError {
  public readonly validationType: 'format' | 'security' | 'schema' | 'content';
  public readonly lineNumber?: number;
  public readonly details: string[];
}

Sources: src/core/errors.ts:100-130

Testing

The security validator includes comprehensive test coverage:

Sources: src/core/security-validator.test.ts:1-50

Test Implementation:

it('detects dangerous commands', () => {
  const content = makeContent('Run rm -rf /');
  const result = validator.validate(content);
  expect(result.issues.some(i => i.type === 'dangerous_command')).toBe(true);
  expect(result.severity).toBe('unsafe');
});

it('detects code injection patterns', () => {
  const content = makeContent('Use ${VARIABLE} in template');
  const result = validator.validate(content);
  expect(result.issues.some(i => i.description.includes('Variable expansion'))).toBe(true);
});

Configuration

Security validation behavior can be configured through the import workflow:

Warning: Setting skipValidation: true bypasses all security checks and should only be used for trusted, locally-verified content.

Sources: examples/usage-examples.md:80-100

Line Number Tracking

The validator tracks the line number for each detected issue:

private getLineNumber(content: string, index: number): number {
  const lines = content.substring(0, index).split('\n');
  return lines.length;
}

This enables precise error reporting showing exactly where issues were found in the skill content.

Sources: src/core/security-validator.ts:200-210

Security Recommendations

When working with skills from external sources:

1. Always validate first - Use validate_skill before importing unknown skills
2. Review issue descriptions - Understand what triggered each warning
3. Prefer GitHub sources - Skills from GitHub are automatically verified
4. Use warning-level skills with caution - Review content before proceeding
5. Never skip validation for untrusted sources - The unsafe designation exists for protection

Related Pages

Related topics: Core Modules

Format Conversion

The Format Conversion system is a core component of the Skill Loader MCP Server that transforms Claude Skills (represented in markdown with YAML frontmatter) into Kiro-compatible formats for use in AI agent contexts. This system provides bidirectional conversion capabilities through the ConversionEngine class and exposes conversion functionality via MCP tools.

Overview

The conversion system serves as a bridge between two ecosystems:

Claude Skills follow a specific structure with YAML frontmatter containing metadata (name, description, dependencies) and a markdown body with instructions and sections. Kiro, by contrast, supports two distinct consumption patterns: lightweight steering files for simple guidance and comprehensive power packages for complex, multi-file skills.

Architecture

Core Components

graph TD
    A[Claude Skill Markdown] --> B[ConversionEngine]
    B --> C[parseSkill]
    C --> D[ParsedSkill]
    D --> E{Output Format}
    E --> F[toSteeringFile]
    E --> G[toPower]
    F --> H[SteeringFile]
    G --> I[PowerStructure]
    
    H --> J[.kiro/steering/*.md]
    G --> K[POWER.md]
    G --> L[mcp.json]
    G --> M[steering/ directory]

The ConversionEngine class located in src/core/conversion-engine.ts is the central orchestrator for all conversion operations. It provides three primary public methods:

Sources: src/core/conversion-engine.ts:38-200

Data Models

The conversion engine works with several interconnected TypeScript interfaces:

interface SkillFrontmatter {
  name: string;
  description: string;
  dependencies?: string[];
  // ... additional fields
}

interface SkillSection {
  heading: string;
  level: number;
  content: string;
}

interface ParsedSkill {
  frontmatter: SkillFrontmatter;
  body: string;
  sections: SkillSection[];
}

interface SteeringFile {
  filename: string;
  content: string;
  metadata: {
    originalSkill: string;
    sourceUrl?: string;
    importedAt: string;
  };
}

interface PowerStructure {
  powerName: string;
  files: Array<{ path: string; content: string }>;
}

Sources: src/core/conversion-engine.ts:1-50

Skill Parsing

Frontmatter Extraction

The parseSkill method extracts YAML frontmatter using a regex pattern:

const frontmatterRegex = /^---\n([\s\S]*?)\n---/;

This pattern matches content between --- delimiters at the document start. The extracted YAML is then parsed using the js-yaml library into a JavaScript object.

Sources: src/core/conversion-engine.ts:55-90

Validation Rules

The parser enforces the following validation rules:

if (!content || content.trim().length === 0) {
  const error = new ValidationError(
    'Skill content is empty',
    'content',
    { details: ['The skill file contains no content'] }
  );
  ErrorLogger.log(error);
  throw error;
}

Sources: src/core/conversion-engine.ts:55-65

Section Extraction

The parser splits the markdown body into hierarchical sections based on heading levels (H1-H6). Each section captures:

• heading: The text following the # symbols
• level: The heading depth (1-6)
• content: The markdown content following the heading

const sectionRegex = /^(#{1,6})\s+(.+)\n([\s\S]*?)(?=\n#{1,6}\s|\n*$)/gm;

This regex preserves code blocks with language annotations, allowing syntax-highlighted examples to pass through unchanged.

Sources: src/core/conversion-engine.ts:70-150

Keyword Extraction

The private extractKeywords method generates up to 5 relevant keywords from the skill description:

1. Converts text to lowercase
2. Removes special characters
3. Filters out common stop words
4. Keeps words with 3+ characters
5. Returns the first 5 matches

private extractKeywords(description: string): string[] {
  const stopWords = new Set([
    'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into',
    'when', 'what', 'where', 'how', 'why', 'can', 'will', 'should',
    // ... additional stop words
  ]);
  
  const words = description
    .toLowerCase()
    .replace(/[^a-z0-9\s]/g, ' ')
    .split(/\s+/)
    .filter(word => word.length >= 3 && !stopWords.has(word))
    .slice(0, 5);
  
  return words;
}

Sources: src/core/conversion-engine.ts:180-220

Steering File Conversion

Output Format

Steering files are designed for simple, single-file skill guidance. They are saved with a kebab-case filename derived from the skill name and placed in .kiro/steering/ directories.

Conversion Process

graph LR
    A[ParsedSkill] --> B[Generate Filename]
    B --> C[kebab-case + .md]
    A --> D[Build Content]
    D --> E[Title from name]
    D --> F[Description section]
    D --> G[Complex sections]
    D --> H[Dependencies list]
    A --> I[Create Metadata]
    I --> J[originalSkill]
    I --> K[sourceUrl]
    I --> L[importedAt]
    E --> M[SteeringFile]
    F --> M
    G --> M
    H --> M
    I --> M

Content Structure

A steering file contains these sections in order:

1. Title: # {skill.name} Guidelines
2. Description: From frontmatter if present
3. Complex Sections: Sections with level ≥ 2 and content length > 200 characters
4. Dependencies: Bulleted list if dependencies exist
5. Footer: Attribution message

Filename Generation

The toSteeringFile method uses toKebabCase to transform skill names:

private toKebabCase(str: string): string {
  return str
    .toLowerCase()
    .replace(/[\s_]+/g, '-')
    .replace(/[^a-z0-9-]/g, '')
    .replace(/-+/g, '-')
    .replace(/^-|-$/g, '');
}

Transformation examples:

Sources: src/core/conversion-engine.ts:120-160

Steering File Output

return {
  filename,
  content,
  metadata: {
    originalSkill: skill.frontmatter.name,
    sourceUrl,
    importedAt: now
  }
};

Sources: src/core/conversion-engine.ts:190-200

Power Conversion

Output Format

Power format is more comprehensive, supporting multi-file outputs for complex skills. The toPower method can generate up to three files:

Sources: src/core/conversion-engine.ts:200-280

Power Manifest Structure

The POWER.md file follows Kiro's power specification:

Related Pages

Related topics: Skill Discovery, Type Definitions

Caching System

Overview

The Caching System in the Skill Loader MCP Server provides an in-memory caching layer with TTL (Time To Live) support. It is designed to reduce redundant API calls to external services like skills.sh, improving response times and reducing network overhead.

The cache implementation is generic and reusable, supporting any data type through TypeScript generics. It automatically expires entries after a configurable TTL and provides basic cache management operations.

Key Characteristics:

• In-memory storage using Map data structure
• Configurable TTL per cache instance
• Automatic expiration checking on access
• Zero external dependencies

Sources: src/utils/cache.ts:1-60

Related Pages

Related topics: Core Modules, Caching System

Type Definitions

This page documents the type system for the Skill Loader MCP Server, covering core data models, error classes, and validation types used throughout the application.

Overview

The Skill Loader MCP Server uses TypeScript for type-safe development. The type system is organized around several key domains:

• Skill Data Models: Structures for representing Claude Skills and their components
• Error Handling: Hierarchical error classes with context and recovery suggestions
• Security Validation: Types for security issue detection and severity levels
• API Responses: Standardized response formats for MCP tools

Sources: src/core/types.ts，src/core/errors.ts

Core Data Models

Skill Structure

The skill data model represents Claude Skills with their metadata and content sections.

classDiagram
    class SkillFrontmatter {
        +string name
        +string description
        +string[] dependencies
    }
    class SkillSection {
        +number level
        +string heading
        +string content
    }
    class ParsedSkill {
        +SkillFrontmatter frontmatter
        +string body
        +SkillSection[] sections
    }
    class ConversionResult {
        +string filename
        +string content
        +Record metadata
    }
    
    ParsedSkill *-- SkillFrontmatter
    ParsedSkill *-- SkillSection
    ConversionResult ..> ParsedSkill

SkillFrontmatter

The frontmatter contains skill metadata defined in YAML format at the top of skill files.

Sources: src/core/conversion-engine.ts (示例展示结构)

ParsedSkill

A fully parsed skill document containing all extracted components.

Sources: src/core/conversion-engine.ts

SkillSection

Represents a heading section within a skill document.

Error Class Hierarchy

The error system uses a hierarchical class structure for granular error handling.

classDiagram
    class Error {
        +string message
        +string name
        +Date timestamp
        +string stack
    }
    
    class SkillLoaderError {
        +Date timestamp
        +Record context
        +getDetailedMessage()
    }
    
    class NetworkError {
        +string url
        +number? statusCode
        +number retryCount
        +getUserMessage()
    }
    
    class ValidationError {
        +string validationType
        +number? lineNumber
        +string[] details
    }
    
    class FileSystemError {
        +string operation
        +string filePath
        +string? systemError
    }
    
    class ParsingError {
        +string parseType
        +string? invalidContent
        +getUserMessage()
    }
    
    Error <|-- SkillLoaderError
    SkillLoaderError <|-- NetworkError
    SkillLoaderError <|-- ValidationError
    SkillLoaderError <|-- FileSystemError
    SkillLoaderError <|-- ParsingError

Base Class: SkillLoaderError

All application errors extend the base SkillLoaderError class.

class SkillLoaderError extends Error {
  public readonly timestamp: Date;
  public readonly context: Record<string, any>;
}

Sources: src/core/errors.ts

NetworkError

Handles network-related failures including connection issues, timeouts, and HTTP errors.

class NetworkError extends SkillLoaderError {
  public readonly url: string;
  public readonly statusCode?: number;
  public readonly retryCount: number;
}

Sources: src/core/errors.ts

Recovery suggestions by status code:

ValidationError

Represents validation failures for format, security, schema, or content issues.

class ValidationError extends SkillLoaderError {
  public readonly validationType: 'format' | 'security' | 'schema' | 'content';
  public readonly lineNumber?: number;
  public readonly details: string[];
}

Sources: src/core/errors.ts

FileSystemError

Handles file system operations including read, write, delete, and access errors.

class FileSystemError extends SkillLoaderError {
  public readonly operation: 'read' | 'write' | 'delete' | 'access';
  public readonly filePath: string;
  public readonly systemError?: string;
}

System error code mappings:

Sources: src/core/errors.ts

Security Validation Types

ValidationIssue

Represents a detected security or content issue.

interface ValidationIssue {
  type: 'dangerous_command' | 'suspicious_pattern' | 'untrusted_source' | 'suspicious_file_op';
  description: string;
  location: string;
}

Sources: src/core/security-validator.ts

ValidationResult

Complete validation outcome with severity classification.

interface ValidationResult {
  isValid: boolean;
  issues: ValidationIssue[];
  severity: 'safe' | 'warning' | 'unsafe';
}

Severity determination rules:

graph TD
    A[ValidationResult] --> B{issues.length === 0?}
    B -->|Yes| C[Return safe]
    B -->|No| D{Has untrusted_source?}
    D -->|Yes| E[Return unsafe]
    D -->|No| F{Has dangerous_command?}
    F -->|Yes| E
    F -->|No| G[Return warning]

Sources: src/core/security-validator.ts

API Response Types

SkillsShEntry

Represents a skill entry from skills.sh directory.

interface SkillsShEntry {
  name: string;
  description: string;
  owner: string;
  repo: string;
  installs: number;
  relevance?: number;
  rank?: number;
  trending?: boolean;
}

SkillsShV1Response

API response wrapper for skills.sh v1 endpoints.

interface SkillsShV1Response {
  skills: SkillsShEntry[];
  total?: number;
  page?: number;
  pageSize?: number;
}

ConversionResponse

Response format for skill conversion operations.

interface ConversionResponse {
  success: boolean;
  content: string;
  filename: string;
  targetPath: string;
  metadata: {
    skillName: string;
    sourceUrl?: string;
    outputFormat: 'steering' | 'power';
    validationResult: ValidationResult;
  };
}

Sources: examples/usage-examples.md

MCP Tool Parameters

Tool Input Schemas

Configuration Types

Server Configuration

interface ServerConfig {
  SKILLS_SH_API_KEY?: string;
  cache?: {
    skillsTTL: number;  // Default: 3600000 (1 hour)
  };
  retry?: {
    maxRetries: number;
    baseDelay: number;
  };
}

Type Naming Conventions

Per project coding standards:

Sources: CONTRIBUTING.md

Summary

The type system provides:

1. Type-safe data models for skills, sections, and metadata
2. Hierarchical error handling with context and recovery suggestions
3. Security validation with issue categorization and severity levels
4. Standardized API responses for all MCP tools

All types are defined in TypeScript with proper JSDoc documentation for IDE support and generated documentation.

Sources: CHANGELOG.md

Related Pages

Related topics: Getting Started, Error Handling

Deployment and Configuration

Overview

The Skill Loader MCP Server provides a comprehensive deployment model for integrating Claude skill management capabilities into various AI development environments. The deployment architecture supports multiple integration patterns, including integration with Kiro, Claude Desktop, and standalone operation modes. Configuration is primarily driven through environment variables and MCP server configuration files, enabling flexible deployment scenarios ranging from simple local installations to enterprise-scale distributed setups.

The server operates as a Model Context Protocol (MCP) server that exposes eight distinct tools for skill management operations. These tools interact with external services including the skills.sh marketplace API and GitHub repositories containing skill definitions. The deployment model emphasizes security through content validation, caching strategies for performance optimization, and comprehensive error handling mechanisms that provide actionable feedback for administrators and users alike.

Installation Methods

Global Installation

Global installation provides system-wide access to the Skill Loader MCP Server, making it immediately available to all projects and users on a given system. This approach is recommended for scenarios where multiple projects require access to skill management capabilities without individual per-project configuration.

The global installation is performed using npm with the -g flag, which installs the package in the global npm registry location. For systems with multiple Node.js versions or requiring specific version management, npx can be used to execute the package directly without permanent installation.

npm install -g @goldzulu/skill-loader-mcp-server

Sources: README.md:49

Local Installation

Local installation is appropriate for project-specific deployments where the skill loader should be tracked as a project dependency. This approach ensures version consistency across team members and facilitates reproducible builds through package.json dependency management.

npm install @goldzulu/skill-loader-mcp-server

Sources: README.md:53

Development Installation

For contributors setting up the development environment, the installation process includes additional steps for building the TypeScript source and running tests. The development setup requires Node.js, npm or yarn, and Git for version control.

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Sources: CONTRIBUTING.md:14-19

Environment Variables

The Skill Loader MCP Server uses environment variables to configure runtime behavior and authentication. Understanding the distinction between required and optional environment variables is critical for successful deployment.

SKILLS_SH_API_KEY

The SKILLS_SH_API_KEY environment variable provides authentication for the skills.sh marketplace API. This key is required only for tools that access authenticated endpoints of the skills.sh service.

Sources: README.md:57-58

The API key must be requested from Vercel, the platform hosting the skills.sh service. Organizations planning to use the authenticated listing and leaderboard features should coordinate with the skills.sh team to obtain appropriate credentials.

MCP Server Configuration

The Skill Loader MCP Server implements the Model Context Protocol specification version 1.29, utilizing the official @modelcontextprotocol/sdk for protocol compliance. Configuration varies depending on the target platform and deployment scenario.

Kiro Configuration

Integration with Kiro requires modification of the mcp.json configuration file. The server can be launched using npx for immediate execution or configured as a persistent server service.

{
  "mcpServers": {
    "skill-loader": {
      "command": "npx",
      "args": ["-y", "@goldzulu/skill-loader-mcp-server"],
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      },
      "description": "Skill Loader MCP Server for managing Claude skills"
    }
  }
}

Sources: README.md:65-76

The configuration specifies the npx command with the -y flag to automatically confirm package installation. The args array passes the package name as an argument to npx. The env block configures the skills.sh API key, which is optional and only required when accessing authenticated endpoints.

Claude Desktop Configuration

Claude Desktop users can integrate the Skill Loader MCP Server by adding the server configuration to their Claude Desktop configuration file. The configuration structure differs slightly from Kiro, using the skill-loader-mcp-server command directly rather than npx invocation.

{
  "mcpServers": {
    "skill-loader": {
      "command": "skill-loader-mcp-server",
      "env": {
        "SKILLS_SH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Sources: README.md:87-97

The Claude Desktop configuration omits the description field and uses the globally installed command directly. This approach assumes the package has been installed globally via npm.

Standalone Operation

For scenarios requiring direct execution without MCP integration, the server can be launched in standalone mode. This mode is useful for testing, debugging, or batch processing operations where the full MCP protocol overhead is unnecessary.

skill-loader-mcp-server

Sources: README.md:99-101

Deployment Architecture

The deployment architecture follows a layered design that separates concerns between protocol handling, core business logic, and external service integration.

graph TD
    A[Client Application] -->|MCP Protocol| B[MCP Server Layer]
    B -->|Request Dispatch| C[Tool Handlers]
    C --> D1[list_skills]
    C --> D2[search_skills]
    C --> D3[get_leaderboard]
    C --> D4[fetch_skill]
    C --> D5[validate_skill]
    C --> D6[convert_to_steering]
    C --> D7[convert_to_power]
    C --> D8[import_skill]
    D1 --> E[Skills.sh API Client]
    D2 --> E
    D3 --> E
    D4 --> F[GitHub Fetcher]
    E --> G[(Skills.sh API)]
    F --> H[(GitHub)]
    D5 --> I[Security Validator]
    D6 --> J[Conversion Engine]
    D7 --> J
    D8 --> K[Complete Workflow]
    K --> D4
    K --> D5
    K --> D7
    J --> L[(Output Files)]
    I --> M[Error Handler]
    M --> N[User Feedback]

Tool Configuration Parameters

Each MCP tool exposed by the server accepts specific parameters that control its behavior. Understanding these parameters is essential for effective configuration and usage.

search_skills

The search_skills tool searches the skills.sh marketplace using the public search API. No authentication is required for this endpoint.

Sources: README.md:109-118

list_skills

The list_skills tool retrieves paginated results from the authenticated skills.sh directory endpoint. This tool requires the SKILLS_SH_API_KEY environment variable.

Sources: README.md:122-131

get_leaderboard

The get_leaderboard tool retrieves trending or top-installed skills, sorted by installation count or trending score.

Sources: README.md:135-144

fetch_skill

The fetch_skill tool retrieves raw skill content directly from GitHub repositories. The tool supports both shorthand skill names and fully-qualified owner/repo identifiers.

Sources: README.md:148-156

validate_skill

The validate_skill tool performs security analysis on skill content, scanning for dangerous patterns and potential security risks.

Sources: README.md:160-168

convert_to_steering

The convert_to_steering tool transforms skill content into the Kiro steering file format, which is used for providing behavioral guidelines to AI models.

Sources: README.md:173-181

convert_to_power

The convert_to_power tool generates the Kiro power format, which includes additional components for complex skills. When a skill has dependencies or MCP server references, the tool automatically generates an mcp.json configuration file. For skills containing three or more complex sections, the tool creates a steering/ subdirectory with structured content.

Sources: README.md:185-193

import_skill

The import_skill tool orchestrates the complete import workflow, combining fetch, validation, and conversion operations in a single atomic transaction.

Sources: README.md:198-207

Security Configuration

The security validation system is a critical component of the deployment configuration, providing defense-in-depth against potentially malicious skill content.

Validation Checks

The security validator scans skill content for multiple categories of risk:

Sources: README.md:212-220

Validation Bypass

The skipValidation parameter on the import_skill tool allows administrators to bypass security checks when importing trusted skills. This parameter should be used cautiously and only for skills from verified sources.

{
  "tool": "import_skill",
  "arguments": {
    "identifier": "trusted/author/skill-name",
    "outputFormat": "power",
    "skipValidation": false
  }
}

Sources: examples/usage-examples.md:175-183

Error Handling Configuration

The error handling system provides structured error responses that enable programmatic error recovery and user-friendly error messages.

Error Response Format

All tools return errors in a consistent JSON format that includes the error message, affected tool name, and timestamp:

{
  "error": "Error message describing what went wrong",
  "tool": "tool_name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Sources: examples/usage-examples.md:220-226

Error Categories

The error handling system classifies errors into distinct categories, each with specific recovery suggestions:

Sources: examples/usage-examples.md:228-236

Custom Error Classes

The error handling infrastructure includes specialized error classes that provide contextual information for different failure scenarios. The FileSystemError class captures operation type, file path, and system-level error details for file-related failures.

Sources: src/core/errors.ts:1-50

The ParsingError class tracks parser type, line numbers, column positions, and code snippets for format-related failures, enabling precise identification of parsing issues in skill content.

Caching Configuration

The server implements in-memory caching for skills.sh directory results to optimize performance and reduce API load.

Cache Behavior

Sources: README.md:224-228

The caching strategy balances performance optimization with data freshness, automatically refreshing cached data when the TTL expires. This approach reduces API calls for frequently accessed data while ensuring users receive current information.

Typical Workflow Configuration

The repository documentation provides recommended workflow patterns for common deployment scenarios.

Discovery and Import Workflow

graph LR
    A[Search Skills] --> B[Evaluate Results]
    B --> C{Find Skill?}
    C -->|Yes| D[List with Pagination]
    C -->|No| E[Refine Search]
    D --> F[Fetch Skill]
    F --> G[Validate Content]
    G --> H{Valid?}
    H -->|Yes| I[Convert Format]
    H -->|No| J[Report Issues]
    I --> K[Import Complete]

For discovering skills, users should first search using the search_skills tool to find relevant skills by keyword. When multiple results exist, the list_skills tool provides paginated browsing of the full directory.

Sources: examples/usage-examples.md:200-212

Validation Workflow

When importing skills from unknown sources, a two-step validation approach is recommended:

1. Fetch the skill: Retrieve the raw content using fetch_skill
2. Validate the content: Use validate_skill to scan for security issues
3. Convert if safe: Apply convert_to_steering or convert_to_power if validation passes

{ "tool": "fetch_skill", "arguments": { "identifier": "unknown/skill" } }

{ "tool": "validate_skill", "arguments": { "content": "...", "url": "..." } }

Sources: examples/usage-examples.md:215-228

Complete Import Workflow

For streamlined operations, the import_skill tool combines all steps into a single atomic operation:

``json { "tool": "get_leaderboard", "arguments": { "timeframe": "24h", "limit": 20 } } ``

1. Search for trending skills:

``json { "tool": "import_skill", "arguments": { "identifier": "owner/skill-name", "outputFormat": "power" } } ``

1. Import a trending skill:

Sources: examples/usage-examples.md:195-200

Project Structure Reference

The deployment configuration is organized within a structured project layout that separates core functionality, tool implementations, and utilities:

skill-loader-mcp-server/
├── src/
│   ├── core/           # Core functionality
│   │   ├── conversion-engine.ts
│   │   └── errors.ts
│   ├── tools/          # MCP tool implementations
│   ├── utils/          # Utility functions
│   ├── index.ts        # Main entry point
│   └── cli.ts          # CLI entry point
├── examples/           # Usage examples
├── dist/               # Compiled output
└── tests/              # Test files

Sources: CONTRIBUTING.md:26-35

The dist/ directory contains the compiled JavaScript output from the TypeScript source, which is the code actually executed during deployment. The examples/ directory provides configuration examples and usage documentation that inform deployment procedures.

Version History

The deployment and configuration capabilities have evolved through the following version milestones:

Sources: CHANGELOG.md:1-40

Related Pages

Related topics: Security Validation, Deployment and Configuration

Error Handling

The Skill Loader MCP Server implements a comprehensive error handling system designed to provide consistent, informative, and actionable error feedback across all MCP tools. The system follows a hierarchical class structure that categorizes errors by their domain (validation, file system, network) and provides context-rich error messages with recovery suggestions.

Architecture Overview

The error handling system is built on a base SkillLoaderError class that extends the native Error class, adding structured metadata and context tracking. This design enables consistent error formatting across all tools while maintaining type safety and enabling programmatic error handling.

graph TD
    A[Error Occurs] --> B{SkillLoaderError}
    B --> C[ValidationError]
    B --> D[FileSystemError]
    B --> E[NetworkError]
    C --> C1[security validation]
    C --> C2[format validation]
    D --> D1[read/write/delete/access]
    E --> E1[connection timeout]
    E --> E2[rate limiting]
    
    style A fill:#ff6b6b
    style B fill:#4ecdc4
    style C fill:#45b7d1
    style D fill:#96ceb4
    style E fill:#ffeaa7

Error Class Hierarchy

Base Class: SkillLoaderError

The base error class provides common functionality for all error types:

Sources: src/core/errors.ts:1-50

ValidationError

Thrown when skill content fails security or format validation checks:

export class ValidationError extends SkillLoaderError {
  public readonly validationType: 'security' | 'format';
  public readonly details?: string[];
}

Validation Types:

1. Security Validation - Triggered when dangerous patterns are detected:

• Dangerous commands (rm -rf, sudo, eval, exec)
• Suspicious file operations (/etc/, /usr/, /bin/)
• Code injection patterns (${...}, $(...))
• Untrusted sources (non-GitHub URLs)

1. Format Validation - Triggered when skill structure is invalid:

• Malformed YAML frontmatter
• Missing required fields
• Invalid markdown structure

Sources: src/core/errors.ts:60-120

FileSystemError

Handles errors during file operations:

System Error Codes:

Sources: src/core/errors.ts:130-200

NetworkError

Handles connectivity and API-related failures:

export class NetworkError extends SkillLoaderError {
  public readonly url: string;
  public readonly statusCode?: number;
  public readonly retryable: boolean;
}

Retry Behavior:

• retryable: true - Transient errors (timeout, 503, rate limit)
• retryable: false - Permanent failures (404, 401, 403)

Sources: src/core/errors.ts:200-280

Security Validation

The security validator analyzes skill content before import to prevent malicious code execution.

Security Issue Types

graph LR
    A[Skill Content] --> B{Security Validator}
    B --> C[Dangerous Commands]
    B --> D[Suspicious Patterns]
    B --> E[Untrusted Sources]
    
    C --> C1[rm -rf, sudo, eval]
    D --> D1[Code injection, path traversal]
    E --> E1[Non-GitHub URLs]

Severity Levels

Sources: src/core/security-validator.ts:1-50

Validation Response Format

{
  "isValid": false,
  "issues": [
    {
      "type": "dangerous_command",
      "description": "Dangerous recursive delete command (rm -rf)",
      "location": "Line 7: rm -rf /"
    }
  ],
  "severity": "unsafe"
}

Sources: examples/usage-examples.md:30-40

Error Response Format

All MCP tools return errors in a standardized JSON format:

{
  "error": "Error message describing what went wrong",
  "tool": "tool_name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Common Error Scenarios

Sources: README.md:150-170

Error Recovery Suggestions

The error system provides actionable recovery guidance based on error type.

Validation Errors

Suggestions:
- Review the skill content manually
- Contact the skill author about security concerns
- Use a different skill from a trusted source

File System Errors

Suggestions:
- Check file permissions (EACCES/EPERM)
- Free up disk space (ENOSPC)
- Verify the directory exists (ENOENT)
- Use the --overwrite flag to replace existing files (EEXIST)

Network Errors

Suggestions:
- Check internet connection
- Verify GitHub availability
- Retry the request after a short delay
- Use cached results if available

Sources: src/core/errors.ts:180-220

Error Flow Diagram

sequenceDiagram
    participant Tool as MCP Tool
    participant Engine as Conversion Engine
    participant Validator as Security Validator
    participant FS as File System
    
    Tool->>Engine: process(content)
    Engine->>Validator: validate(content)
    
    alt Validation Failed
        Validator-->>Tool: ValidationError
        Tool->>Tool: Return error with suggestions
    end
    
    Engine->>FS: write(output)
    
    alt File System Error
        FS-->>Tool: FileSystemError
        Tool->>Tool: Return error with path info
    end
    
    alt Success
        Validator-->>Engine: isValid: true
        Engine-->>Tool: Success result
    end

Best Practices

1. Always validate before import - Use validate_skill to check content safety
2. Handle errors gracefully - Check for error responses before processing results
3. Use try-catch blocks - Wrap tool calls to handle unexpected errors
4. Check severity levels - Distinguish between warnings and blocking errors
5. Preserve error context - Log error timestamps and tool names for debugging

Sources: examples/usage-examples.md:180-200

Configuration

Error handling behavior can be influenced through these configuration options:

Sources: README.md:140-150

Doramagic Pitfall Log

Doramagic extracted 9 source-linked risk signals. Review them before installing or handing real data to the project.

1. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | host_targets=mcp_host, claude

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | no_demo; severity=medium

6. Security or permission risk: v1.0.0 - Initial Release

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: v1.0.0 - Initial Release. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.0.0

7. Security or permission risk: v1.1.0 — skills.sh API migration & Power format update

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: v1.1.0 — skills.sh API migration & Power format update. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/goldzulu/skill-loader-mcp-server/releases/tag/v1.1.0

8. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | issue_or_pr_quality=unknown

9. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1148400928 | https://github.com/goldzulu/skill-loader-mcp-server | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using skill-loader-mcp-server with real data or production workflows.

• v1.1.0 — skills.sh API migration & Power format update - github / github_release
• v1.0.0 - Initial Release - github / github_release
• Configuration risk needs validation - GitHub / issue