Related Pages

Related topics: Installation and Quick Start, System Architecture

Project Overview

suggest-skills is a Model Context Protocol (MCP) server and CLI tool that helps AI agents discover, compare, and manage available skills from remote manifests and locally installed skill collections. The project serves as a bridge between remote skill repositories and AI agent workflows, enabling intelligent skill suggestion without requiring immediate installation.

Purpose and Scope

The primary purpose of suggest-skills is to provide AI agents with a systematic way to:

• Fetch available skills from configured remote manifests
• Scan locally installed skills in a standardized directory structure
• Compare remote and local capabilities to identify gaps and opportunities
• Present suggestions to users without forcing immediate installation

The project acts as a skill discovery layer, not a skill executor. It identifies what skills exist and recommends which ones might be useful based on context, but leaves the actual installation and execution to separate processes. Sources: README.md

Technology Stack

suggest-skills is built with modern JavaScript/TypeScript tooling optimized for server-side execution in AI agent environments.

Sources: README.md, package.json

Architecture Overview

The project follows a layered architecture with clear separation between configuration, tool registration, and transport layers.

graph TD
    A[Configuration<br/>Environment Variables] --> B[Config Validation<br/>ConfigError]
    B --> C[MCP Tool Registration<br/>suggest_skills, fetch_manifest<br/>download_skill]
    C --> D[Transport Layer]
    D --> E[stdio Mode<br/>stdin/stdout]
    D --> F[HTTP Mode<br/>localhost:3100]
    
    G[GitHub API] --> H[download_skill tool]
    I[Remote Manifests] --> J[suggest_skills tool]
    J --> K[Local Skills Scanner]

Sources: README.md

Core Components

1. Configuration System

The configuration layer validates environment settings and provides defaults for all operational parameters.

The configuration accepts manifest URLs in multiple formats:

• JSON array: ["https://example.com/manifest.md"]
• Comma-separated: https://a.com/manifest.md,https://b.com/manifest.md
• Newline-separated: https://a.com/manifest.md\nhttps://b.com/manifest.md

Sources: README.md

2. MCP Tools

The server exposes three primary MCP tools for agent interaction:

#### suggest_skills

Accepts an optional manifestUrl to overwrite the default configuration. Returns a generated instruction payload that tells an agent how to discover and compare skills.

Parameters:

#### fetch_manifest

Accepts a manifest URL and returns its raw text content for parsing.

Parameters:

#### download_skill

Downloads all files from a GitHub folder, preserving directory structure and file content.

Parameters:

Returns:

• Path relative to the requested folder
• UTF-8 text content
• Resolved symlinks for GitHub-provided download URLs

Sources: README.md

3. CLI Commands

The command-line interface provides two primary operations:

#### Generate Mode

npx suggest-skills generate [options] <github-url>

Options:

Output Files:

• <owner>.<repo>[.<path>].skills.md - Skill entries from directories containing SKILL.md
• <owner>.<repo>[.<path>].designs.md - Design entries from directories containing DESIGN.md
• <owner>.<repo>[.<path>].agents.md - Agent entries from flat markdown files with Name and Description columns

#### Server Mode

npx suggest-skills server --port <number>

Starts the HTTP transport server for remote MCP connections.

Sources: README.md

Transport Modes

suggest-skills supports dual transport mechanisms for different deployment scenarios:

graph LR
    A[Agent] -->|stdio| B[suggest-skills]
    A -->|HTTP| C[localhost:3100/mcp]
    
    B --> D[Local Skills]
    C --> D
    
    C --> E[Health Check<br/>/health]
    
    D --> F[Remote Manifests<br/>via GitHub API]

Stdio Mode

Suitable for local agent integration where the MCP server runs as a child process:

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

HTTP Mode

Suitable for networked deployments where the agent connects remotely:

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

Sources: README.md

GitHub Integration

The download functionality integrates with GitHub's API to fetch skill packages:

URL Processing

The system automatically handles GitHub URL normalization:

• Converts github.com/blob/ URLs to raw.githubusercontent.com format
• Supports tree URLs for directory downloads
• Uses GitHub Contents API for file retrieval

Download Flow

sequenceDiagram
    participant Agent
    participant Server as suggest-skills
    participant GitHub as GitHub API
    
    Agent->>Server: download_skill(folderUrl)
    Server->>GitHub: GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1
    GitHub-->>Server: Tree structure with file/blob entries
    Server->>GitHub: For each file: GET /repos/{owner}/{repo}/contents/{path}
    GitHub-->>Server: File contents
    Server-->>Agent: Array of {path, download_url, type, content}

Sources: src/download.ts

Project Structure

suggest-skills/
├── src/
│   ├── download.ts      # GitHub folder download logic
│   └── generate.ts      # Manifest generation logic
├── official/            # Official bundled skills
├── community/           # Community-contributed skills
├── .github/
│   └── workflows/
│       └── generate-manifests.yml  # Cron-based manifest updates
├── package.json
└── README.md

The repository maintains both official and community skill manifests, updated daily via a cron workflow that scans skill directories and generates indexed markdown files. Sources: README.md

Coding Standards

The codebase adheres to several architectural principles:

Sources: README.md

Workflow Integration

The typical agent workflow using suggest-skills follows this pattern:

1. Initialization: Agent loads suggest-skills MCP server with manifest URLs
2. Discovery: Agent calls suggest_skills to get guidance on available capabilities
3. Comparison: Agent scans local .agents/skills directory against remote manifests
4. Recommendation: Agent presents available skills without forcing installation
5. Installation: On user request, agent uses download_skill to fetch specific packages

This separation allows agents to provide informed recommendations while deferring resource-intensive installation operations until explicitly requested.

Sources: README.md

Key Features Summary

Related Pages

Related topics: Project Overview, Runtime Modes

Installation and Quick Start

Overview

suggest-skills is a Model Context Protocol (MCP) server that helps AI agents discover, compare, and suggest skills from configured manifests and locally installed skill repositories. The tool enables agents to understand available capabilities without requiring immediate installation, facilitating intelligent skill recommendations for various tasks.

The server operates in two modes:

• stdio mode: Direct integration with AI agent tooling via standard input/output
• HTTP mode: Streamable HTTP server for remote agent connections

Sources: README.md

Prerequisites

Before installing suggest-skills, ensure your environment meets the following requirements:

Sources: README.md

Installation Methods

Method 1: NPX (Recommended for Quick Start)

The simplest way to run suggest-skills without installation:

npx suggest-skills

Method 2: Global Installation

For frequent use, install globally via npm:

npm install -g suggest-skills

Method 3: Local Project Installation

For project-specific usage:

npm install suggest-skills

Method 4: Build from Source

git clone https://github.com/sator-imaging/suggest-skills.git
cd suggest-skills
bun install
bun build

Sources: README.md

Configuration

Environment Variables

The server requires configuration through environment variables:

#### Configuration Examples

JSON array format:

SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md", "https://other.com/skills.md"]' \
npx suggest-skills

Comma-separated format:

SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest.md,https://other.com/skills.md' \
npx suggest-skills

Newline-separated format:

SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest.md
https://other.com/skills.md' \
npx suggest-skills

Sources: README.md

Manifest URL Conversion

The system automatically converts GitHub blob URLs to raw.githubusercontent.com URLs:

# Input (blob URL)
https://github.com/OWNER/REPO/blob/HEAD/skills/manifest.md

# Automatically converted to
https://raw.githubusercontent.com/OWNER/REPO/main/skills/manifest.md

Sources: README.md

Running the Tool

stdio Mode

Standard I/O mode for direct agent integration:

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills

HTTP Mode

Streamable HTTP server for remote agent connections:

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100

Sources: README.md

CLI Commands

Generate Command

Create markdown inventories from GitHub skill directories:

npx suggest-skills generate <github-url>

Options:

Examples:

# Generate from skills directory
npx suggest-skills generate https://github.com/OWNER/REPO/tree/main/skills

# Generate with recursive scanning
npx suggest-skills generate --recursive https://github.com/OWNER/REPO/tree/main/skills

# Generate with custom output directory
npx suggest-skills generate -o ./my-skills https://github.com/OWNER/REPO/tree/main/skills

Generate Output Files

The generate command creates the following files in the current working directory:

Server Command

Start the HTTP MCP server:

npx suggest-skills server --port <number>

Sources: README.md

MCP Tools

The server provides three MCP tools for agent interaction:

suggest_skills

Returns a generated instruction payload that tells an agent how to:

• Fetch available skills from configured manifests
• Scan locally installed skills
• Compare remote and local capabilities
• Present suggestions without installing until requested

{
  "manifestUrl": "optional-override-url"
}

fetch_manifest

Fetches and returns the text content of a manifest URL:

{
  "manifestUrl": "https://example.com/manifest.md"
}

download_skill

Downloads all files from a GitHub folder URL:

{
  "folderUrl": "https://github.com/<owner>/<repo>/tree/<ref>/<path>"
}

Returns each file with:

• Path relative to the requested folder
• UTF-8 text content
• Symlinks resolved and downloaded recursively

Sources: README.md

Project Architecture

graph TD
    A[Config] --> B[MCP Tool Registration]
    B --> C[Stdio Transport]
    B --> D[HTTP Transport]
    
    E[CLI Generate] --> F[GitHub Directory Scan]
    E --> G[Manifest Markdown File]
    
    H[GitHub URL Normalization] --> F
    H --> I[Folder Download]
    
    J[GitHub API] --> K[Tree API]
    J --> L[Contents API]
    
    K --> M[Recursive Discovery]
    L --> M

Technology Stack

Sources: README.md

Coding Standards

The codebase follows these implementation patterns:

• Modular design: Small, focused modules with runtime concerns split by file
• Config validation: Explicit validation through ConfigError class
• Typed schemas: Tool schemas with structured output for MCP tools
• Minimal transport wrappers: Lightweight wrappers around shared server creation
• Behavior-driven tests: Tests focused on observable behavior rather than implementation details

Sources: README.md

Troubleshooting

Common Issues

Health Check Verification

For HTTP mode, verify the server is running:

curl http://localhost:3100/health

Sources: README.md

Next Steps

After completing installation:

1. Configure manifests: Set up SUGGEST_SKILLS_MANIFEST_URLS with your skill repositories
2. Explore official skills: Browse the official skills directory
3. Explore community skills: Browse the community skills directory
4. Generate custom manifests: Use the CLI to create skill inventories from any GitHub repository
5. Integrate with agents: Connect the MCP server to your AI agent tooling

Related Pages

Related topics: Core Components, MCP Tools Reference

System Architecture

Overview

suggest-skills is an MCP (Model Context Protocol) server and CLI tool that helps AI agents discover, compare, and manage skills from configured manifests and local installations. The system provides a unified interface for skill discovery without requiring immediate installation, enabling agents to make informed decisions about which capabilities to load. Sources: README.md:1-50

Technology Stack

Sources: README.md:180-190

High-Level Architecture

graph TD
    subgraph "Configuration Layer"
        ENV[Environment Variables]
        CLI[CLI Arguments]
        CFG[Config Validator]
    end

    subgraph "Transport Layer"
        STDIO[Stdio Transport]
        HTTP[HTTP Server Transport]
    end

    subgraph "Core Layer"
        MCP[MCP Tool Registration]
        CORE[Core Logic]
    end

    subgraph "External Services"
        GITHUB[GitHub API]
        MANIFEST[Skill Manifests]
    end

    ENV --> CFG
    CLI --> CFG
    CFG --> MCP
    MCP --> STDIO
    MCP --> HTTP
    CORE --> GITHUB
    CORE --> MANIFEST

    style Configuration Layer fill:#e1f5fe
    style Transport Layer fill:#fff3e0
    style Core Layer fill:#e8f5e9

The architecture follows a layered approach where configuration flows downward to tool registration, which then branches into transport modes. Sources: README.md:192-205

Core Components

Project Architecture Pattern

Config -> MCP tool registration -> stdio or HTTP transport
  CLI generate -> GitHub directory scan -> manifest markdown file
               \-> GitHub URL normalization / folder download

Sources: README.md:192-205

Directory Structure

src/
├── index.ts       # Entry point and server initialization
├── config.ts      # CLI argument parsing and configuration
├── core.ts        # Core business logic
├── download.ts    # GitHub folder download utilities
└── generate.ts    # Manifest generation logic

Component Responsibilities

Sources: src/config.ts:1-80

MCP Tools

The server exposes three primary MCP tools for agent interaction:

Tool Specifications

Sources: README.md:130-170

`download_skill` Tool

Accepts GitHub folder URLs in the format:

https://github.com/<owner>/<repo>/tree/<ref>/<path>

Returns files with:

• Path relative to requested folder
• UTF-8 text content
• Resolved symlinks for repository-relative directory symlinks

Sources: README.md:155-165

CLI Interface

Command Structure

graph LR
    A[suggest-skills] --> B[generate]
    A --> C[download]
    A --> D[server]
    A --> E[stdio mode]

    B --> F[<url>]
    B --> G[-r --recursive]
    C --> H[<url>]
    C --> I[-r --recursive]
    D --> J[--port <number>]

Sources: src/config.ts:1-50

CLI Commands

CLI Options

Sources: src/config.ts:10-60

Configuration System

Environment Variables

Manifest URL Formats

Accepted formats for SUGGEST_SKILLS_MANIFEST_URLS:

• JSON array: ["https://some/skill-manifest.md"]
• Comma-separated string: https://one/skill.md,https://two/skills.md
• Newline-separated string
• GitHub blob URLs auto-converted to raw.githubusercontent.com

Sources: README.md:208-230

Configuration Validation

interface CliRuntimeMode {
  kind: "generate" | "download" | "server" | "stdio";
  url?: string;
  recursive?: boolean;
  config: {
    outputDirectory: string;
    sourceUrls: string[];
  };
}

Sources: src/config.ts:50-80

Transport Modes

Stdio Mode

Default mode for local agent integration:

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

Messages exchanged via standard input/output streams. Sources: README.md:238-242

HTTP Server Mode

Streamable HTTP transport for distributed deployments:

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

Sources: README.md:245-252

GitHub Integration

API Integration Flow

sequenceDiagram
    participant CLI as CLI/Server
    participant API as GitHub API
    participant FS as File System

    CLI->>API: Request directory tree (recursive)
    API-->>CLI: Tree structure with paths and SHAs
    CLI->>API: Request contents for each file
    API-->>CLI: File contents
    CLI->>FS: Write files to output directory

    Note over CLI: buildTreeApiUrl()
    Note over CLI: buildContentsApiUrl()

Sources: src/download.ts:30-80

URL Building Utilities

Sources: src/download.ts:30-70

Directory Scanning Logic

The generate command scans directories with these rules:

1. Discover SKILL.md and DESIGN.md in skill directories
2. Bundle assets are files next to or nested within skill directories
3. Empty generated outputs are skipped
4. Symlinks are not traversed specially; may appear in bundled assets

Sources: src/generate.ts:1-80 Sources: README.md:90-100

Coding Standards

The codebase adheres to specific implementation patterns:

• Modularity: Small, focused modules with runtime concerns split by file
• Validation: Explicit config validation through ConfigError
• Typing: Typed tool schemas and structured output for MCP tools
• Testing: Observable behavior over implementation detail
• Transport: Minimal wrappers around shared server creation

Sources: README.md:207-215

Manifest Generation

Output Files

The generate command produces markdown files:

Generation Rules

• GitHub directory discovery uses recursive tree listing internally
• SKILL.md and DESIGN.md are discovered in skill directories
• Bundled assets are files next to them or in nested subdirectories
• Symlinks found are not handled specially
• Empty outputs are skipped silently

Sources: README.md:83-100

Data Flow Diagrams

Stdio Mode Data Flow

graph TD
    A[User/Agent] -->|Stdin| B[MCP Server]
    B -->|Parse Command| C[Config Validator]
    C -->|Valid Config| D[Tool Executor]
    D -->|suggest_skills| E[Fetch Manifests]
    D -->|fetch_manifest| F[HTTP Request]
    D -->|download_skill| G[GitHub API]
    E -->|Skill List| B
    F -->|Manifest Text| B
    G -->|File Contents| B
    B -->|Stdout| A

HTTP Server Mode Data Flow

graph TD
    A[Remote Agent] -->|HTTP POST /mcp| B[HTTP Server]
    B -->|Forward| C[MCP Handler]
    C -->|Execute| D[Tool Executor]
    D -->|GitHub API| E[External Services]
    C -->|Response| B
    B -->|HTTP Response| A
    F[Health Check] -->|GET /health| B
    B -->|200 OK| F

Configuration Error Handling

The system validates configuration at startup and throws ConfigError for:

• Missing required environment variables
• Invalid manifest URL formats
• Invalid CLI argument combinations

Sources: src/config.ts:60-80

Related Pages

Related topics: System Architecture, MCP Tools Reference

Core Components

Overview

The suggest-skills project implements an MCP (Model Context Protocol) server that provides skill discovery and installation capabilities for AI agents. The core components handle configuration management, skill suggestion logic, GitHub repository scanning, and manifest generation.

The system operates in two primary modes: stdio mode for direct CLI interaction and HTTP mode for network-accessible MCP endpoints. Sources: README.md

Architecture Overview

graph TD
    subgraph "Transport Layer"
        STDIO[Stdio Transport]
        HTTP[HTTP Transport]
    end
    
    subgraph "Core Components"
        CONFIG[Config Module]
        CONSTANTS[Constants Module]
        UTILS[Utils Module]
    end
    
    subgraph "MCP Tools"
        SUGGEST[Suggest Skills Tool]
        FETCH[Fetch Manifest Tool]
        DOWNLOAD[Download Skill Tool]
    end
    
    subgraph "CLI Components"
        GENERATE[Generate Module]
    end
    
    STDIO --> SERVER[Server Creation]
    HTTP --> SERVER
    SERVER --> CONFIG
    SERVER --> SUGGEST
    SERVER --> FETCH
    SERVER --> DOWNLOAD
    SERVER --> GENERATE
    
    CONFIG --> CONSTANTS
    CONFIG --> UTILS

Component Breakdown

1. Config Module (`src/config.ts`)

The Config module handles application configuration validation and management.

Responsibilities:

• Validates required environment variables
• Parses manifest URLs from configuration
• Handles ConfigError exceptions for invalid configurations

Environment Variables:

Configuration Flow:

graph LR
    A[Environment Variables] --> B[Config Parser]
    B --> C{Valid Manifest URLs?}
    C -->|Yes| D[Return Valid Config]
    C -->|No| E[Throw ConfigError]

Sources: src/config.ts

2. Constants Module (`src/constants.ts`)

The Constants module defines reusable values used across the application.

Key Constants:

The module also defines type aliases and reusable schema patterns for MCP tool inputs. Sources: src/constants.ts

3. Utils Module (`src/utils.ts`)

The Utils module provides shared utility functions used by multiple components.

Core Utilities:

Path Handling:

graph TD
    A[GitHub Path] --> B{Nested Directory?}
    B -->|No| C[Immediate Entry]
    B -->|Yes| D[Create Dir Entry]
    D --> E[Recursive Processing]

The utility functions handle path normalization by removing leading slashes and ensuring consistent URL construction. Sources: src/utils.ts

4. Suggest Module (`src/suggest.ts`)

The Suggest module implements the suggest_skills MCP tool that generates instruction payloads for skill discovery.

Tool Interface:

Workflow:

graph TD
    A[Suggest Request] --> B{manifestUrl Provided?}
    B -->|Yes| C[Use Provided URL]
    B -->|No| D[Load from Config]
    C --> E[Fetch Available Skills]
    D --> E
    E --> F[Scan Local Skills]
    F --> G[Compare Remote vs Local]
    G --> H[Generate Instruction Payload]
    H --> I[Return to Agent]

Instruction Payload Contents:

• How to fetch skills from configured manifests
• How to scan locally installed skills
• Comparison logic for remote and local capabilities
• Presentation format for suggestions without installation

Sources: src/suggest.ts

5. Download Module (`src/download.ts`)

The Download module handles GitHub repository folder downloads with recursive symlink resolution.

GitHub Directory Resolution:

Download Process:

graph TD
    A[GitHub Folder URL] --> B[Parse Location]
    B --> C[Build Contents API URL]
    C --> D[Fetch Tree Recursively]
    D --> E{Entry Type?}
    E -->|tree| F[Add Dir Entry]
    E -->|blob| G[Build Raw URL]
    G --> H[Add File Entry]
    F --> I[Return Entries]
    H --> I

URL Construction:

function buildGithubRawUrl(owner: string, repo: string, ref: string, path: string): string

The module transforms blob entries into downloadable URLs using raw.githubusercontent.com. Sources: src/download.ts

6. Generate Module (`src/generate.ts`)

The Generate module creates markdown inventory files from GitHub skills directories.

Discovery Rules:

Generation Flow:

graph TD
    A[GitHub URL] --> B[Recursive Tree Listing]
    B --> C[Scan for SKILL.md]
    B --> D[Scan for DESIGN.md]
    C --> E[Collect Assets per Dir]
    D --> E
    E --> F{File Type?}
    F -->|SKILL.md| G[Set skillFileUrl]
    F -->|DESIGN.md| H[Set designFileUrl]
    F -->|Other| I[Add to Assets]
    G --> J[Write Manifest Files]
    H --> J
    I --> J
    J --> K[Skip Empty Outputs]

Asset Collection:

• Bundled assets are files next to SKILL.md or DESIGN.md
• Nested subdirectory contents are included
• Symlinks are downloaded when GitHub provides download_url
• Repository-relative symlinks are resolved recursively

Symlink Handling:

• Symlinks with download_url are followed and downloaded
• Directory symlinks are traversed recursively
• Symlinks without download_url are skipped

Sources: src/generate.ts

Data Models

GitHub Directory Location

interface GithubDirectoryLocation {
  owner: string;
  repo: string;
  ref: string;
  path: string;
}

Content Entry

interface ContentEntry {
  path: string;
  download_url: string | null;
  type: "file" | "dir";
}

Directory Summary

interface DirectorySummary {
  skillFileUrl?: string;
  designFileUrl?: string;
  assets: string[];
}

CLI Mode

Generate Command

npx suggest-skills generate \
  https://github.com/OWNER/REPO/tree/main/skills

Options:

• -r, --recursive: Scan directories recursively
• -o, --output <dir>: Output directory (default: .agents/skills)

Server Command

npx suggest-skills server --port 3100

HTTP Mode

Default Port: 3100

Type Safety

The project uses Zod for schema validation at runtime:

• Tool input schemas
• Configuration validation
• Structured output for MCP tools

This ensures type safety beyond compile-time checks. Sources: README.md

Technology Stack

Summary

The core components follow a layered architecture:

1. Configuration manages environment setup and validation
2. Constants provide shared values across modules
3. Utils offer reusable path and file handling utilities
4. Suggest generates skill discovery instructions for agents
5. Download handles GitHub repository content retrieval
6. Generate creates markdown manifests from skill directories

The separation allows the MCP server to operate in both stdio and HTTP transport modes while sharing core business logic. Sources: src/config.ts, src/constants.ts, src/utils.ts, src/suggest.ts, src/download.ts, src/generate.ts

Related Pages

Related topics: System Architecture, Runtime Modes

MCP Tools Reference

This document provides comprehensive documentation for the Model Context Protocol (MCP) tools exposed by the suggest-skills server. These tools enable AI agents to dynamically discover, fetch, and download skill manifests and skill assets from GitHub repositories.

Overview

The MCP Tools Reference documents the three primary tools exposed by the suggest-skills MCP server:

These tools follow the MCP specification using the @modelcontextprotocol/sdk and leverage Zod for runtime schema validation.

Sources: README.md

Architecture

System Components

graph TD
    A["CLI / Server Entry"] --> B["Config Module<br/>(config.ts)"]
    B --> C["MCP Tool Handlers"]
    
    C --> D["suggest_skills<br/>(suggest.ts)"]
    C --> E["fetch_manifest<br/>(suggest.ts)"]
    C --> F["download_skill<br/>(download.ts)"]
    
    D --> G["Skill Manifest URLs"]
    E --> H["GitHub API / Raw Content"]
    F --> H
    
    G --> I["Local Skills Scan"]
    H --> J["Downloaded Assets"]
    
    K["Transport Layer"] -->|"stdio"| C
    K -->|"HTTP"| L["Streamable HTTP Server<br/>(http.ts)"]

Transport Modes

The MCP server supports two transport mechanisms:

Sources: README.md:58-72

Tool Specifications

`suggest_skills`

Purpose: Generates an instruction payload that guides an AI agent through the skill discovery workflow.

Input Parameters:

Workflow Steps:

graph TD
    A["Invoke suggest_skills"] --> B{"manifestUrl provided?"}
    B -->|Yes| C["Use provided URL"]
    B -->|No| D["Read from SUGGEST_SKILLS_MANIFEST_URLS"]
    C --> E["Generate instruction payload"]
    D --> E
    E --> F["Return structured instructions"]
    
    F --> G["Agent: Fetch available skills"]
    G --> H["Agent: Scan local skills"]
    H --> I["Agent: Compare remote vs local"]
    I --> J["Agent: Present suggestions"]
    J --> K["Wait for user confirmation"]
    K --> L["Agent: Install selected skills"]

Output: Returns a generated instruction payload containing guidance for:

• Fetching available skills from configured manifests
• Scanning locally installed skills
• Comparing remote and local capabilities
• Presenting suggestions without installing until requested

Sources: README.md:48-57

`fetch_manifest`

Purpose: Retrieves the raw text content of a skill manifest file from a given URL.

Input Parameters:

Behavior:

1. Accepts a manifest URL
2. Performs HTTP GET request to the specified URL
3. Returns the raw UTF-8 text content of the manifest

URL Processing:

The tool automatically handles GitHub blob URLs by converting them to raw.githubusercontent.com format:

Input:  https://github.com/owner/repo/blob/HEAD/skills/manifest.md
Output: https://raw.githubusercontent.com/owner/repo/main/skills/manifest.md

Sources: README.md:48-57

`download_skill`

Purpose: Downloads complete skill directories from GitHub, including all bundled assets.

Input Parameters:

Behavior:

graph TD
    A["download_skill URL"] --> B["Parse GitHub URL"]
    B --> C["Build Contents API URL"]
    B --> D["Fetch Git Tree SHA"]
    
    C --> E["Call GitHub Contents API"]
    D --> E
    
    E --> F{"Entry Type"}
    F -->|"tree"| G["Create directory entry"]
    F -->|"blob"| H["Build raw download URL"]
    
    G --> I["Collect all entries"]
    H --> I
    
    I --> J["Return file list with paths and download URLs"]
    
    J --> K["Download all files"]
    K --> L["Resolve symlinks recursively"]
    L --> M["Save to output directory"]

Return Structure:

{
  path: string;        // Relative path from requested folder
  download_url: string | null;  // null for directories
  type: "file" | "dir";
}

Special Handling:

• File symlinks: Downloaded when GitHub provides a download_url
• Directory symlinks: Resolved and downloaded recursively
• Empty outputs: Skipped silently, no file written

Sources: README.md:48-57 Sources: src/download.ts:30-60

Configuration

Environment Variables

Manifest URL Formats:

Sources: README.md:60-73

CLI Options

Sources: src/config.ts:1-30

Usage Examples

Stdio Mode

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

HTTP Mode

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

This exposes:

• MCP endpoint: http://localhost:3100/mcp
• Health check: http://localhost:3100/health

Sources: README.md:66-72

Generate Manifests

npx suggest-skills generate \
  https://github.com/OWNER/REPO/tree/main/skills

With recursive scanning:

npx suggest-skills generate \
  --recursive \
  https://github.com/OWNER/REPO/tree/main/skills

Generated Output Files:

Sources: README.md:28-45

Data Models

GitHub Directory Location

Used internally for parsing and building GitHub URLs:

interface GithubDirectoryLocation {
  owner: string;
  repo: string;
  ref: string;
  path: string;
}

Content Entry

Returned by the download tool to represent files and directories:

interface ContentEntry {
  path: string;           // Relative path from requested folder
  download_url: string | null;  // null for directories
  type: "file" | "dir";
}

CLI Runtime Mode

Defines the operational mode of the CLI:

type CliRuntimeMode =
  | { kind: "generate"; url: string; recursive: boolean; config: CliConfig }
  | { kind: "download"; url: string; recursive: boolean; config: CliConfig }
  | { kind: "server"; port?: number }
  | { kind: "stdio"; config: CliConfig };

Sources: src/config.ts:15-45 Sources: src/download.ts:30-60

Technology Stack

Sources: README.md:75-81

Coding Standards

The MCP tools implementation follows these architectural patterns:

1. Modular Design: Small, focused modules with runtime concerns split by file
2. Explicit Validation: Configuration errors raised through ConfigError
3. Typed Schemas: Zod schemas for tool input validation
4. Structured Output: Consistent return types for all tools
5. Minimal Transport: Clean wrappers around shared server creation
6. Behavior-Driven Tests: Focus on observable behavior over implementation details

Sources: README.md:83-94

Related Pages

Related topics: Environment Variables, Manifest Generation

CLI Commands

The suggest-skills CLI provides a command-line interface for generating skill manifests, downloading skills, and running the MCP server in different modes. The CLI is built using the cac (Command And Argument) parser and supports multiple runtime modes that determine how the application executes.

Architecture Overview

graph TD
    A[CLI Entry] --> B[parseCli]
    B --> C{Runtime Mode}
    C -->|generate| D[onGenerate]
    C -->|download| E[onDownload]
    C -->|server| F[onServer]
    C -->|stdio| G[onStdio]
    D --> H[generate.ts]
    E --> I[download.ts]
    F --> J[MCP Server]
    G --> J

Command Structure

The CLI uses cac for argument parsing and supports four primary commands. Each command maps to a specific runtime mode that configures how the application processes requests. Sources: src/config.ts:26-54

Global Options

Generate Command

The generate command scans a GitHub repository directory and produces markdown inventory files listing available skills, agents, and designs.

Usage

npx suggest-skills generate \
  https://github.com/OWNER/REPO/tree/main/skills

npx suggest-skills generate \
  --recursive \
  https://github.com/OWNER/REPO/tree/main/skills

Output Files

The generate command may write the following files in the current working directory:

• <owner>.<repo>[.<path>].skills.md - Entries collected from skill directories containing SKILL.md
• <owner>.<repo>[.<path>].designs.md - Entries collected from skill directories containing DESIGN.md
• <owner>.<repo>[.<path>].agents.md - Entries collected from flat top-level markdown files with Name and Description columns

Empty generated outputs are skipped automatically. Sources: README.md:59-75

Discovery Rules

The generate mode uses these rules for discovery:

• GitHub directory discovery uses a recursive tree listing internally
• SKILL.md and DESIGN.md are discovered in skill directories
• Bundled assets include files next to them or in nested subdirectories
• Symlinks found during generate are not handled specially and may appear in bundled assets Sources: README.md:77-81

Markdown Table Formatting

The cmd_generate.ts module handles formatting of generated markdown tables with special character escaping.

function escapeTableCell(value: string): string {
  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
}

#### Empty Document Detection

Generated documents that contain only headers without any data rows are considered empty:

function isEmptyGeneratedDocument(document: GeneratedDocument): boolean {
  return document.markdown === "| Name | Description |\n| -----|-------------|\n"
    || document.markdown === "| Name | Description | Bundled Assets |\n| -----|-------------|----------------|\n";
}

#### Bundled Assets Formatting

Assets are formatted inline when the count is below the threshold, otherwise summarized. Sources: src/cmd_generate.ts:1-50

Download Command

The download command retrieves all files from a GitHub folder, including skills, agents, and designs.

Usage

npx suggest-skills download \
  https://github.com/<owner>/<repo>/tree/<ref>/<path>

GitHub API Integration

The download functionality builds GitHub API URLs dynamically:

#### Contents API URL

function buildContentsApiUrl(location: GithubDirectoryLocation): string {
  const pathSuffix = location.path
    .split("/")
    .filter(Boolean)
    .map((part) => encodeURIComponent(part))
    .join("/");
  const pathname = pathSuffix
    ? `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents/${pathSuffix}`
    : `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents`;
  const url = new URL(pathname, GITHUB_API_BASE_URL);
  url.searchParams.set("ref", location.ref);
  return url.toString();
}

#### Tree API URL

For recursive operations, the tree API provides efficient directory traversal:

function buildTreeApiUrl(owner: string, repo: string, treeSha: string): string {
  const pathname = `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/trees/${encodeURIComponent(treeSha)}`;
  const url = new URL(pathname, GITHUB_API_BASE_URL);
  url.searchParams.set("recursive", "1");
  return url.toString();
}

#### Raw URL Construction

function buildGithubRawUrl(owner: string, repo: string, ref: string, path: string): string {
  // Returns raw.githubusercontent.com URL for file downloads
}

Sources: src/download.ts:1-80

Server Command

Runs the streamable HTTP server for MCP tool access.

Usage

npx suggest-skills server --port 3100

Endpoints

Stdio Mode

Default mode where the MCP server communicates via standard input/output.

Usage

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

Runtime Mode Types

The CLI parses commands into structured runtime modes:

type CliRuntimeMode =
  | { kind: "generate"; url: string; recursive: boolean; config: ... }
  | { kind: "download"; url: string; recursive: boolean; config: ... }
  | { kind: "server"; port?: number; config: ... }
  | { kind: "stdio"; config: ... };

Sources: src/config.ts:56-75

Configuration

CLI runtime modes incorporate configuration from environment variables:

GitHub blob URLs are converted to raw.githubusercontent.com URLs automatically. Sources: README.md:83-97

CLI Parsing Flow

sequenceDiagram
    participant User
    participant CLI as parseCli()
    participant CAC
    participant Actions
    
    User->>CLI: process.argv
    CLI->>CAC: Create cac instance
    CAC->>Actions: Register commands
    Actions->>CAC: Define onGenerate/onDownload/onServer/onStdio
    User->>CAC: Run command
    CAC->>Actions: Call matching action
    Actions->>CLI: Return CliRuntimeMode
    CLI->>User: Execute with mode

Entry Point

The main entry point is src/index.ts which initializes the CLI and handles the selected runtime mode. The parseCli() function is called with process.argv and process.env to determine the appropriate execution path. Sources: src/index.ts()

Default Output Directory

The default output directory for installed skills is .agents/skills when using the -o or --output option. Sources: src/config.ts:30

Summary

The suggest-skills CLI provides four distinct commands for different use cases:

1. generate - Create markdown inventories from GitHub skill repositories
2. download - Fetch skill files from GitHub to local storage
3. server - Run as HTTP MCP server
4. stdio - Run as stdio-based MCP server (default)

All commands share common options for output directory specification and recursive processing, making the CLI flexible for both one-time operations and automated workflows.

Related Pages

Related topics: CLI Commands, Runtime Modes

Environment Variables

The suggest-skills project uses environment variables for configuration management, enabling flexible deployment across different execution contexts (CLI, MCP server modes). Configuration is centralized in src/config.ts with explicit validation through ConfigError to ensure required variables are properly set before runtime.

Overview

Environment variables in suggest-skills serve two primary purposes:

1. Authentication: Enable authenticated GitHub API requests for higher rate limits
2. Manifest Configuration: Define which skill manifests the agent should reference

Sources: README.md

graph TD
    A[Application Start] --> B{Validate Config}
    B -->|Missing SUGGEST_SKILLS_MANIFEST_URLS| C[Throw ConfigError]
    B -->|Valid Config| D[Load Manifest URLs]
    D --> E{Optional GITHUB_PAT?}
    E -->|Yes| F[Enable Authenticated Requests]
    E -->|No| G[Use Anonymous Requests]
    F --> H[Register MCP Tools]
    G --> H

Configuration Variables

Required Variables

The SUGGEST_SKILLS_MANIFEST_URLS variable is validated at startup. If omitted, the application throws a ConfigError and terminates. This ensures the agent always has at least one manifest to reference for skill suggestions.

Sources: README.md

Supported Format Types

The SUGGEST_SKILLS_MANIFEST_URLS variable accepts multiple input formats:

The configuration loader automatically parses any of these formats, normalizing them into an internal array for manifest fetching operations.

Sources: README.md

Optional Variables

When GITHUB_PAT is provided, all GitHub API calls use Bearer token authentication. Without it, requests are made anonymously, which may encounter stricter rate limiting from GitHub.

Sources: README.md

URL Processing

GitHub Blob URL Conversion

The system automatically converts GitHub blob URLs to raw.githubusercontent.com format for content retrieval:

Input:  https://github.com/owner/repo/blob/HEAD/skills/manifest.md
Output: https://raw.githubusercontent.com/owner/repo/main/skills/manifest.md

Sources: README.md

This conversion happens during manifest URL validation, ensuring consistent URL handling throughout the codebase regardless of how users reference GitHub-hosted manifests.

graph LR
    A[Manifest URL Input] --> B{Is GitHub Blob URL?}
    B -->|Yes| C[Extract Owner/Repo/Ref/Path]
    C --> D[Build Raw URL]
    B -->|No| E[Use as-is]
    D --> F[Fetch Content]
    E --> F

CLI Usage Patterns

Stdio Mode (Default MCP)

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

Sources: README.md

HTTP Server Mode

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

The HTTP endpoint is served at http://localhost:3100/mcp with health check at http://localhost:3100/health.

Sources: README.md

Generate Mode with Authentication

GITHUB_PAT=ghp_xxx \
SUGGEST_SKILLS_MANIFEST_URLS='["https://github.com/org/repo/skills/manifest.md"]' \
  npx suggest-skills generate \
  --recursive \
  https://github.com/OWNER/REPO/tree/main/skills

When generating manifests recursively, authenticated requests improve reliability when traversing large repository trees.

Configuration Validation

The configuration module implements explicit validation with descriptive error messages:

// Conceptual validation flow from src/config.ts
function validateConfig(): void {
  const manifestUrls = process.env.SUGGEST_SKILLS_MANIFEST_URLS;
  
  if (!manifestUrls || manifestUrls.trim() === "") {
    throw new ConfigError(
      "SUGGEST_SKILLS_MANIFEST_URLS is required and must contain at least one URL"
    );
  }
  
  // Parse and normalize URL formats...
}

Sources: src/config.ts

Configuration Override Mechanism

MCP Tool Override

The suggest_skills MCP tool accepts an optional manifestUrl parameter that overwrites the configured SUGGEST_SKILLS_MANIFEST_URLS at runtime:

Sources: README.md

This allows agents to dynamically reference different manifest sources without modifying environment configuration.

Architecture Summary

graph TD
    subgraph "Configuration Layer"
        A[Environment Variables] --> B[config.ts]
        B --> C{ConfigError?}
    end
    
    subgraph "Manifest Processing"
        C -->|Valid| D[Parse Manifest URLs]
        D --> E[Normalize GitHub Blob URLs]
        E --> F[Fetch Manifest Content]
        F --> G[fetch_manifest Tool]
    end
    
    subgraph "Tool Registration"
        G --> H[suggest_skills]
        H --> I[MCP Server]
    end
    
    subgraph "GitHub API Integration"
        A -->|GITHUB_PAT| J[Authenticated Client]
        J --> K[download_skill Tool]
    end

Best Practices

1. Always set SUGGEST_SKILLS_MANIFEST_URLS before launching the application
2. Use GITHUB_PAT for production deployments to avoid rate limiting
3. Validate URL accessibility before deploying manifest configurations
4. Use JSON array format for multiple URLs when shell quoting is not a concern

Error Handling

Related Pages

Related topics: Manifest Generation, MCP Tools Reference

Bundled Skills Reference

Overview

Bundled Skills Reference is a curated collection of prebuilt skill manifests available within the suggest-skills repository. These manifests provide machine-readable inventories of skills, agents, and designs that can be consumed by MCP (Model Context Protocol) clients. The reference aggregates skill definitions from multiple upstream sources including official repositories (Anthropic, OpenAI, Google Labs) and community-contributed collections.

Sources: README.md

Architecture

Skill Manifest Structure

Each bundled manifest follows a structured format containing skill entries with metadata and file references:

graph TD
    A[Manifest URL] --> B[Skill Entry]
    B --> C[Name]
    B --> D[Description]
    B --> E[Trigger Keywords]
    B --> F[Bundled Files]
    F --> G[SKILL.md]
    F --> H[DESIGN.md]
    F --> I[agents/*.yaml]
    F --> J[assets/*]
    F --> K[references/*]
    F --> L[scripts/*]

Sources: official/skills/ALL.md

Repository Organization

graph LR
    A[suggest-skills repo] --> B[official/skills/]
    A --> C[community/skills/]
    B --> D[anthropics.skills.md]
    B --> E[openai.skills.skills.md]
    B --> F[google-labs-code.stitch-skills.md]
    C --> G[ComposioHQ.*.md]
    C --> H[obra.superpowers.skills.md]

Official Skills

Anthropic Skills

The Anthropic skills collection provides capabilities for common AI assistant workflows.

Sources: official/skills/anthropics.skills.md

OpenAI Skills

The OpenAI skills collection focuses on integration with OpenAI platforms and Codex.

Sources: official/skills/openai.skills.skills.md

Google Labs Code Stitch Skills

The Stitch skills collection provides UI/UX design integration capabilities.

Sources: official/skills/google-labs-code.stitch-skills.md

Community Skills

ComposioHQ Awesome-Claude-Skills

A collection of community-contributed skills for various use cases.

Sources: community/skills/ComposioHQ.awesome-claude-skills.md

OBRA Superpowers

Skills focused on improving agent capabilities for writing and planning.

Sources: community/skills/obra.superpowers.skills.md

Skill Directory Structure

Each skill directory follows a consistent file organization pattern:

skill-name/
├── SKILL.md              # Required: Main skill definition
├── DESIGN.md             # Optional: Design specifications
├── LICENSE.txt           # License file
├── agents/               # Agent configuration files
│   └── openai.yaml       # Agent definitions with Name/Description
├── assets/               # Static assets (images, templates)
│   ├── icon.png
│   └── preview.png
├── references/           # Reference documentation
│   ├── api.md
│   └── guide.md
├── scripts/              # Helper scripts
│   └── helper.sh
└── evaluations/          # Evaluation/test data (optional)
    └── test-cases.yaml

Sources: official/skills/ALL.md

MCP Tools Integration

suggest_skills

Returns a generated instruction payload that tells an agent how to fetch, scan, and compare skills.

interface SuggestSkillsParams {
  manifestUrl?: string;  // Optional: overwrite default manifest URLs
}

fetch_manifest

Retrieves raw manifest content from a configured URL.

interface FetchManifestParams {
  manifestUrl: string;  // Required: URL of the skill manifest
}

download_skill

Downloads all files from a GitHub folder URL.

interface DownloadSkillParams {
  folderUrl: string;  // Format: https://github.com/{owner}/{repo}/tree/{ref}/{path}
}

Returns files with:

• Path relative to the requested folder
• UTF-8 text content
• Resolved symlinks when GitHub provides download_url

Sources: README.md

Configuration

Environment Variables

Manifest URL Formats

Accepted formats for SUGGEST_SKILLS_MANIFEST_URLS:

["https://some/skill-manifest.md"]

https://some/skill-manifest.md,https://other/skill-manifest.md

https://some/skill-manifest.md
https://other/skill-manifest.md

GitHub blob URLs are automatically converted to raw.githubusercontent.com URLs.

Usage Modes

stdio Mode

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

HTTP Mode

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

Generate Mode

npx suggest-skills generate \
  https://github.com/OWNER/REPO/tree/main/skills

Generates markdown inventories:

• <owner>.<repo>[.<path>].skills.md - entries from skill directories with SKILL.md
• <owner>.<repo>[.<path>].designs.md - entries from skill directories with DESIGN.md
• <owner>.<repo>[.<path>].agents.md - entries from flat markdown files with Name/Description columns

Sources: README.md

Technology Stack

Workflow Diagram

graph TD
    A[Configure manifest URLs] --> B[Start suggest-skills]
    B --> C{Transport Mode}
    C -->|stdio| D[Read from stdin/stdout]
    C -->|HTTP| E[Start HTTP server on port 3100]
    D --> F[MCP Tool: suggest_skills]
    E --> F
    F --> G[Fetch skill manifests]
    G --> H[Compare with local skills]
    H --> I[Present skill suggestions]
    I --> J[User requests skill installation]
    J --> K[MCP Tool: download_skill]
    K --> L[Download skill folder from GitHub]
    L --> M[Save to .agents/skills/]

Key Design Patterns

1. Manifest-driven discovery: Skills are discovered through manifest URLs rather than hardcoded lists
2. Bundled asset support: Each skill can include scripts, references, and assets alongside definitions
3. Symlink resolution: Repository symlinks are automatically resolved during download
4. Lazy installation: Skills are suggested but not installed until explicitly requested

Sources: README.md

Related Pages

Related topics: CLI Commands, Bundled Skills Reference

Manifest Generation

Overview

Manifest Generation is the core feature of suggest-skills that scans GitHub repositories containing skill definitions and produces structured markdown inventory files. These inventories capture available skills, designs, and agents from a repository, enabling the MCP server to provide intelligent skill suggestions to users.

The generation process discovers skill artifacts by traversing GitHub directory trees, identifying files matching specific naming conventions (SKILL.md, DESIGN.md, or agent definition files), and bundling associated assets.

Sources: README.md:1-100

Architecture

graph TD
    A[CLI: npx suggest-skills generate] --> B[cmd_generate.ts]
    B --> C[Parse GitHub URL]
    C --> D[Fetch Git Tree Recursively]
    D --> E[download.ts: fetchGitTree]
    E --> F[Generate.ts: scanDirectoryTree]
    F --> G{File Type?}
    G -->|SKILL.md| H[Mark as Skill Directory]
    G -->|DESIGN.md| I[Mark as Design Directory]
    G -->|agents.md format| J[Mark as Agent Definition]
    G -->|Other files| K[Bundle as Asset]
    H --> L[Build Skills Manifest]
    I --> M[Build Designs Manifest]
    J --> N[Build Agents Manifest]
    K --> L
    K --> M
    L --> O[<owner>.<repo>.skills.md]
    M --> P[<owner>.<repo>.designs.md]
    N --> Q[<owner>.<repo>.agents.md]

CLI Usage

Basic Generation

npx suggest-skills generate \
  https://github.com/OWNER/REPO/tree/main/skills

Recursive Generation

npx suggest-skills generate \
  --recursive \
  https://github.com/OWNER/REPO/tree/main/skills

Output Directory

npx suggest-skills generate \
  -o ./my-skills \
  https://github.com/OWNER/REPO/tree/main/skills

Sources: README.md:70-90

Output File Types

The generate command produces three types of manifest files based on discovery rules:

Skills Manifest

File naming: <owner>.<repo>[.<path>].skills.md

Contains entries from skill directories that contain a SKILL.md file. Each entry includes:

• Skill name
• GitHub URL
• Description
• Associated assets (files bundled with the skill)

Designs Manifest

File naming: <owner>.<repo>[.<path>].designs.md

Contains entries from directories that contain a DESIGN.md file. Supports optional YAML front matter for name and description fields.

Related Pages

Related topics: Installation and Quick Start, MCP Tools Reference

Runtime Modes

The suggest-skills project supports multiple runtime modes to accommodate different integration scenarios. The architecture separates concerns between CLI operations, MCP tool registration, and transport mechanisms, enabling flexible deployment options.

Overview

Runtime modes define how the application starts, processes requests, and communicates with external systems. The project implements a unified configuration system that branches into distinct operational modes based on CLI arguments and environment variables.

graph TD
    A[CLI Entry Point] --> B{parseCli}
    B --> C[stdio Mode]
    B --> D[HTTP Server Mode]
    B --> E[Generate Mode]
    B --> F[Download Mode]
    
    C --> G[MCP Tools]
    D --> H[HTTP Transport]
    E --> I[File Output]
    F --> J[Download Output]

Sources: src/config.ts:1-80

Available Runtime Modes

Sources: README.md:1-100

CLI Runtime Mode Structure

The CLI parsing layer creates a typed runtime mode union that drives all subsequent behavior:

type CliRuntimeMode =
  | { kind: "stdio"; config: Config }
  | { kind: "generate"; url: string; recursive: boolean; config: Config }
  | { kind: "download"; url: string; recursive: boolean; config: Config }
  | { kind: "server"; port?: number; config: Config };

Sources: src/config.ts:20-40

Configuration Sources

Runtime modes inherit configuration from two environment variables:

Sources: README.md:100-120

Stdio Mode

Stdio mode enables the MCP server to communicate via standard input/output streams, making it suitable for direct integration with Claude Desktop or similar tools that spawn subprocesses.

graph LR
    A[Claude Agent] -->|stdin| B[suggest-skills]
    B -->|stdout| A
    B --> C[MCP Tools]
    C --> D[suggest_skills]
    C --> E[fetch_manifest]
    C --> F[download_skill]

Usage

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills

MCP Tools Available

The stdio mode exposes three MCP tools:

Sources: README.md:120-160

HTTP Server Mode

HTTP mode runs a persistent server that exposes the MCP protocol over HTTP, allowing remote clients to access tools via RESTful endpoints.

Usage

SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

Endpoints

graph TD
    A[HTTP Client] -->|POST /mcp| B[MCP Server]
    A -->|GET /health| B
    B --> C[Tool Registration]
    C --> D[suggest_skills]
    C --> E[fetch_manifest]
    C --> F[download_skill]

Sources: README.md:160-180

Generate Mode

Generate mode scans GitHub repositories and produces markdown inventory files without installing anything locally.

Usage

npx suggest-skills generate \
  https://github.com/OWNER/REPO/tree/main/skills

Recursive Scanning

npx suggest-skills generate \
  --recursive \
  https://github.com/OWNER/REPO/tree/main/skills

Output Files

Sources: README.md:60-90

Download Mode

Download mode fetches skill directories and saves them locally for offline use.

Usage

npx suggest-skills download \
  https://github.com/<owner>/<repo>/tree/<ref>/<path>

File Handling

• Symlinks are downloaded when GitHub provides a download_url
• Repository-relative directory symlinks are resolved and downloaded recursively
• Empty generated outputs are skipped automatically

Sources: README.md:80-100

Project Architecture

graph TB
    subgraph "Configuration Layer"
        A[Environment Variables]
        B[Config Validation]
    end
    
    subgraph "Transport Layer"
        C[stdio.ts]
        D[http.ts]
    end
    
    subgraph "CLI Layer"
        E[cli.parse]
        F[Runtime Mode Dispatch]
    end
    
    subgraph "MCP Tools"
        G[suggest_skills]
        H[fetch_manifest]
        I[download_skill]
    end
    
    A --> B
    B --> E
    E --> F
    F -->|stdio| C
    F -->|server| D
    C --> G
    C --> H
    C --> I
    D --> G
    D --> H
    D --> I

Sources: src/index.ts:1-30

Technology Stack

The runtime modes are built on these core technologies:

Sources: README.md:180-200

Environment Configuration

Default Output Directory

When installing skills via download, the default output directory is:

.agents/skills

This can be overridden using the -o <dir> or --output <dir> CLI option.

Manifest URL Formats

Manifest URLs support multiple formats:

Sources: README.md:100-130

Doramagic Pitfall Log

Doramagic extracted 15 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:1220908449 | https://github.com/sator-imaging/suggest-skills | 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:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.

3. Project risk: v1.0.1

• Severity: medium
• Finding: Project risk is backed by a source signal: v1.0.1. Treat it as a review item until the current version is checked.
• 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1

4. Project risk: v1.1.1

• Severity: medium
• Finding: Project risk is backed by a source signal: v1.1.1. Treat it as a review item until the current version is checked.
• 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1

5. Project risk: v1.2.1

• Severity: medium
• Finding: Project risk is backed by a source signal: v1.2.1. Treat it as a review item until the current version is checked.
• 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1

6. Project risk: v1.3.1

• Severity: medium
• Finding: Project risk is backed by a source signal: v1.3.1. Treat it as a review item until the current version is checked.
• 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1

7. Maintenance risk: v1.0.2

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: v1.0.2. 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2

8. Maintenance risk: v1.0.3

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: v1.0.3. 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3

9. Maintenance risk: v2.0.0

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: v2.0.0. 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: Source-linked evidence: https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0

10. 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:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing

11. 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:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium

12. Security or permission risk: No sandbox install has been executed yet; downstream must verify before user use.

• Severity: medium
• Finding: No sandbox install has been executed yet; downstream must verify before user use.
• 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.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using suggest-skills with real data or production workflows.

• v2.0.0 - github / github_release
• v1.3.1 - github / github_release
• v1.3.0 - github / github_release
• v1.2.1 - github / github_release
• v1.1.1 - github / github_release
• v1.0.3 - github / github_release
• v1.0.2 - github / github_release
• v1.0.1 - github / github_release
• Configuration risk needs validation - GitHub / issue