Related Pages

Related topics: System Architecture & Core Components, MCP Tools, CLI & Configuration

Overview & Getting Started

Purpose and Scope

suggest-skills is a Model Context Protocol (MCP) server that recommends and downloads repository-specific AI agent skills. It is published as the npm package suggest-skills (current version 2.0.6) and is licensed under Apache-2.0 Source: [package.json].

The server consumes one or more remote skill manifest files (Markdown tables of Name / Description / Bundled Assets) and exposes tools that an MCP-compatible agent can call to (1) receive contextual skill suggestions for the current repository, (2) fetch a manifest on demand, and (3) download a skill folder from GitHub together with all of its bundled assets. In addition to the MCP runtime, the same codebase ships a generate subcommand that scans a GitHub skills directory and emits three deterministic Markdown inventories (.skills.md, .designs.md, .agents.md) suitable for use as prebuilt manifests.

The repository itself hosts the official and community manifests under official/ and community/, which are the recommended starting points for first-time users.

Architecture

The application is built as a small, focused TypeScript codebase bundled by Bun. Runtime concerns are split across files in src/:

flowchart LR
  CLI[CLI entry<br/>src/config.ts] -->|parses argv| Mode{CliRuntimeMode}
  Mode -->|stdio| StdioServer[MCP stdio server]
  Mode -->|server| HttpServer[MCP HTTP server<br/>:port/mcp]
  Mode -->|generate| Gen[generateOutputs<br/>src/cmd_generate.ts]
  Mode -->|download| Dl[downloadGithubFolder<br/>src/download.ts]

  Gen --> GitAPI[(api.github.com<br/>tree listing)]
  Dl --> GitAPI
  Dl --> Raw[(raw.githubusercontent.com)]
  StdioServer --> Tools
  HttpServer --> Tools

  subgraph Tools[MCP tools]
    T1[suggest_skills]
    T2[download_skill]
    T3[fetch_manifest]
  end

  Tools --> ManifestCache[(in-memory cache<br/>src/download.ts)]

The four runtime shapes are defined as a discriminated union, CliRuntimeMode, in src/config.ts: stdio, generate, download, and server. Each branch delegates to a dedicated module — src/cmd_generate.ts for manifest generation, src/download.ts for GitHub folder downloads and manifest fetching, and shared src/core.ts-style helpers for the MCP server.

Three MCP tools are registered with stable names exported from src/constants.ts:

Installation and Configuration

The package is distributed via npm and can be invoked directly with npx:

npx -y suggest-skills

The shipped package.json declares three runtime dependencies — @modelcontextprotocol/sdk for the MCP transport layer, cac for CLI parsing, and ts-fibers for concurrency control inside the GitHub download path Source: [package.json]. The bin field maps the suggest-skills command to the compiled dist/index.js.

Configuration is driven by two environment variables and an optional output directory flag:

GitHub blob URLs in any input are normalized to raw.githubusercontent.com automatically by src/utils.ts (normalizeGithubRawUrl), and parsed directory URLs flow into parseGithubDirectoryUrl for generate mode.

A minimal MCP client configuration looks like:

{
  "mcpServers": {
    "suggest-skills": {
      "command": "npx",
      "args": [
        "-y",
        "suggest-skills",
        "--",
        "--output=.agents/skills",
        "https://github.com/sator-imaging/suggest-skills/blob/fdd9d327647ed38317daa5613134410af1f0f919/official/official-skills.md"
      ],
      "env": {
        "SUGGEST_SKILLS_MANIFEST_URLS": [
          "https://github.com/sator-imaging/suggest-skills/blob/fdd9d327647ed38317daa5613134410af1f0f919/official/official-skills.md"
        ]
      }
    }
  }
}

Runtime Modes

The default invocation runs the MCP server over stdio. The server subcommand exposes the same tool set over streamable HTTP:

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

The HTTP endpoint is served at http://localhost:3100/mcp. Both transports share the same tool registration code, with the HTTP path adding only a thin transport wrapper Source: [src/config.ts].

The generate subcommand scans a GitHub skills directory and writes three manifests to the current working directory:

• <owner>.<repo>[.<path>].skills.md — entries from directories that contain SKILL.md
• <owner>.<repo>[.<path>].designs.md — entries from directories that contain DESIGN.md
• <owner>.<repo>[.<path>].agents.md — flat top-level Markdown files with YAML front matter

Discovery uses a recursive GitHub tree listing. With --recursive (-r), nested subdirectories are also scanned for SKILL.md and DESIGN.md; without it, only direct children of the generate root are inspected. Symlinks are not traversed, output file names are normalized to remove redundant type suffixes, and empty generated outputs are skipped so that no file is written for them Source: [src/cmd_generate.ts].

The download subcommand mirrors this discovery but writes the actual SKILL.md and bundled assets to disk, preserving their relative paths. The download and generate paths share a MANIFEST_CACHE map in src/download.ts that was introduced in v1.3.0 to deduplicate repeated fetch_manifest calls, and the v2.0.1 release added explicit verification that files were actually written.

Recent Community Activity

Several recent releases are worth noting for new users:

• v2.0.6 (latest) — empty DESIGN manifest entries are now skipped and logged, preventing zero-row files from being produced by generate.
• v2.0.5 — the Security Risk column produced by the SkillSpector CI workflow now embeds the underlying recommendation and stats are split into *Advisory* and *Dangerous* skill tiers.
• v2.0.0 — the deprecated --manifest-urls CLI option was removed; configure manifests only through SUGGEST_SKILLS_MANIFEST_URLS going forward.
• v1.3.0 — an in-memory cache was added to the fetch_manifest tool to reduce repeat network calls.

Security scanning for the curated manifests in this repository is provided by NVIDIA SkillSpector through the CI workflow, which writes a per-skill risk score into the Security Risk column of the generated manifests. As stated in the README, suggest-skills itself does not perform security checks; it is the responsibility of the manifest publisher to keep that column accurate.

See Also

• CLI & Runtime Modes
• MCP Tools Reference
• Manifest Generation
• GitHub Download & URL Handling

Related Pages

Related topics: Overview & Getting Started, MCP Tools, CLI & Configuration

System Architecture & Core Components

Overview & Purpose

suggest-skills is a Model Context Protocol (MCP) server that recommends and retrieves repository-specific AI agent skills from GitHub-hosted manifest files. It exposes three MCP tools — suggest_skills, download_skill, and fetch_manifest — and additionally offers generate and download CLI subcommands that operate on GitHub repository trees to produce local manifest inventories. The codebase is small and module-oriented, built around a shared createServer core reused by stdio and HTTP transports.

Source: package.json:2-3 — "description": "MCP server that suggests repository-specific AI agent skills."

Source: src/constants.ts:1-12 — defines the three tool name constants and their descriptions.

High-Level Architecture

The runtime is driven by a CLI parser that selects one of four runtime modes. Each mode is a tagged variant of CliRuntimeMode containing a shared SuggestSkillsConfig. The MCP server itself is constructed once and shared between stdio and HTTP transports, while generate and download reuse the GitHub downloader and tree analyzer modules.

flowchart LR
    A[CLI Parser<br/>src/config.ts] --> B{Runtime Mode}
    B -->|stdio| C[Stdio Transport]
    B -->|server| D[HTTP Transport<br/>:3100/mcp]
    B -->|generate| E[GitHub Tree Scan<br/>src/cmd_generate.ts]
    B -->|download| F[Folder Downloader<br/>src/download.ts]
    C --> G[createServer Core<br/>src/core.ts]
    D --> G
    G --> H[Tools:<br/>suggest_skills<br/>download_skill<br/>fetch_manifest]
    E --> I[Manifest Writer<br/>*.skills.md / *.designs.md / *.agents.md]
    F --> I
    H --> F

Source: src/config.ts:17-22 — defines the four-variant CliRuntimeMode discriminated union.

Source: src/config.ts:62-83 — onGenerate, onDownload, onServer, and onStdio action handlers that set runtimeMode.

Runtime Modes & CLI Surface

The CLI uses cac and exposes one global option plus four command shapes. The default subcommand runs in stdio mode, while explicit server, generate, and download commands switch behavior.

Source: src/config.ts:34-59 — registerCommands defines each command and its options.

Source: src/config.ts:25 — DEFAULT_OUTPUT_DIRECTORY = ".agents/skills".

Core Components

Configuration Layer

src/config.ts is the single entry point for parsing process arguments and the SUGGEST_SKILLS_MANIFEST_URLS / GITHUB_PAT environment variables. It produces a SuggestSkillsConfig containing outputDirectory and sourceUrls, and raises a ConfigError for invalid input. Both stdio and server modes carry this config into createServer.

Source: src/config.ts:12-15 — SuggestSkillsConfig type and ConfigError class.

URL & Tree Utilities

src/utils.ts and src/generate.ts together implement the GitHub-aware helpers. normalizeGithubRawUrl rewrites github.com/.../blob/<ref>/... links to raw.githubusercontent.com, and parseGithubDirectoryUrl extracts { owner, repo, ref, path } tuples used for recursive tree scans. formatGithubFolderUrl and formatGithubFileUrl build canonical tree/ and blob/ URLs for output manifests.

Source: src/utils.ts:14-39 — normalizeGithubRawUrl implementation.

Source: src/generate.ts:11-19 — folder and file URL formatters.

Downloader & Manifest Cache

src/download.ts performs authenticated api.github.com requests (using the optional GITHUB_PAT) and is reused by the MCP download_skill and fetch_manifest tools as well as the CLI download subcommand. Since v1.3.0, an in-process Map cache stores manifest text keyed by URL to avoid redundant fetches; the cache can be reset for tests via clearManifestCache. Concurrency is bounded by DOWNLOAD_CONCURRENCY = 4.

Source: src/download.ts:24-26 — MANIFEST_CACHE map and clearManifestCache export.

Source: src/download.ts:36-47 — fetchManifestText with cache lookup, and fetchTextContent.

Generator & Output Documents

src/cmd_generate.ts produces three document kinds in parallel: *.skills.md (from SKILL.md directories), *.designs.md (from DESIGN.md directories), and *.agents.md (from top-level agent .md files with front matter). The GENERATED_MARKDOWN_OPTIONS table encodes per-kind settings such as whether to include the Bundled Assets column and whether to inline or link assets. The most recent release (v2.0.6) added handling for empty DESIGN.md entries that previously produced empty manifest files.

Source: src/cmd_generate.ts:34-53 — GENERATED_OUTPUT_KIND_SUFFIXES and GENERATED_MARKDOWN_OPTIONS maps.

Source: src/cmd_generate.ts:55-67 — generateSkillsManifest and generateOutputs entry points.

Configuration & Environment

Two environment variables control runtime behavior:

• GITHUB_PAT (optional): sent as a bearer token to api.github.com for higher rate limits and private repositories.
• SUGGEST_SKILLS_MANIFEST_URLS (required for stdio/server): accepts a JSON array, comma-separated, or newline-separated list of manifest URLs. github.com/.../blob/... links are normalized to raw.githubusercontent.com automatically.

The default subcommand has no positional argument; generate and download accept a single GitHub URL, which is normalized before being passed to the downloader.

Source: src/utils.ts:14-39 — URL normalization for both blob and raw GitHub URLs.

Build, Test & Runtime Dependencies

The project ships as a single npm binary, built with Bun and minified for production. Runtime dependencies are limited to the MCP SDK, the cac CLI parser, and ts-fibers (used by the downloader for concurrent fetches). bun test plus a TypeScript + oxlint check make up the test gate.

Source: package.json:14-19 — build, start, server, check, and test scripts.

Source: package.json:20-24 — dependencies list.

See Also

• Configuration & Environment Variables — full env-var reference and accepted formats
• MCP Tools Reference — schemas for suggest_skills, download_skill, and fetch_manifest
• Generate & Download Workflow — end-to-end walkthrough of generate and download subcommands
• Release History & Security Scanning — SkillSpector CI integration added in v2.0.2

Related Pages

Related topics: System Architecture & Core Components, Manifest Generation, Downloads & Security Scanning

MCP Tools, CLI & Configuration

Overview

suggest-skills is an MCP (Model Context Protocol) server that recommends and downloads repository-specific AI agent skills. It exposes a small, focused tool surface and a CLI that can either run the server (stdio or streamable HTTP) or operate on a GitHub source tree directly via generate / download. The current release is v2.0.6. Source: package.json:2-2

A single parseCli entry point produces a discriminated CliRuntimeMode union that captures the active mode plus a shared SuggestSkillsConfig (output directory and source URLs). Source: src/config.ts:13-26 Server and stdio modes both build their McpServer through createServer, so the registered tool set is identical regardless of transport. Source: src/core.ts:9-9

flowchart LR
    A[env + CLI args] --> B[parseCli]
    B --> C{CliRuntimeMode}
    C -->|stdio| D[McpServer + stdio]
    C -->|server| E[McpServer + HTTP :port/mcp]
    C -->|generate| F[GitHub tree scan -> manifest md]
    C -->|download| G[GitHub folder downloader]
    D --> H[suggest_skills]
    D --> I[fetch_manifest]
    D --> J[download_skill]
    E --> H
    E --> I
    E --> J

MCP Tools

createServer registers three tools on a shared McpServer instance. Source: src/core.ts:9-9 Each tool returns text content intended for an LLM agent.

fetch_manifest consults a module-level MANIFEST_CACHE map before issuing an HTTP request, so repeat lookups for the same URL are served from memory. Source: src/download.ts:21-37 This cache was introduced in v1.3.0. suggest_skills delegates to buildSuggestionResponse, which substitutes the configured manifest URLs and the configured output directory into a static INSTRUCTIONS template that references ${FETCH_MANIFEST_TOOL_NAME} and ${DOWNLOAD_TOOL_NAME}. Source: src/suggest.ts:13-19

CLI Modes & Commands

CLI parsing is implemented with cac and emits one of four CliRuntimeMode variants. Source: src/config.ts:36-67

• generate <url> with optional -r|--recursive: scans a GitHub skills directory or repo root and writes <owner>.<repo>[.<path>].skills.md, …designs.md, and …agents.md into the working directory. Source: src/cmd_generate.ts:73-104 Empty outputs (such as a DESIGN manifest with no entries) are skipped and logged — a fix delivered in v2.0.6.
• download <url> with optional -r|--recursive: downloads skills, agents, and designs to the current directory. Source: src/config.ts:55-59 v2.0.1 added verification that writes actually land on disk before reporting success.
• server --port <number>: starts the streamable HTTP transport at http://localhost:<port>/mcp. Source: README.md:128-131
• default (no subcommand): runs the MCP server in stdio mode, suitable for embedding in an MCP client. Source: src/config.ts:64-67

The global -o, --output <dir> option controls the install directory used by suggest_skills and defaults to .agents/skills. Source: src/config.ts:31-31 In v2.0.0 the deprecated --manifest-urls CLI option was removed; manifest URLs are now sourced from SUGGEST_SKILLS_MANIFEST_URLS and may be passed as positional arguments that are normalized through normalizeGithubRawUrl before being stored on the runtime mode. Source: src/utils.ts:24-39

Configuration

Two environment variables drive the runtime:

• GITHUB_PAT (optional): token used for authenticated requests to api.github.com. Source: README.md:95-97
• SUGGEST_SKILLS_MANIFEST_URLS (required for server and stdio modes): accepts a JSON array, a comma-separated list, or a newline-separated list of manifest URLs. GitHub blob URLs are converted to raw.githubusercontent.com URLs automatically. Source: README.md:97-102

Invalid configuration raises ConfigError, which is defined alongside the config types and propagates out of parseCli. Source: src/config.ts:28-30 Generate mode reads its URLs from CLI arguments rather than the environment and walks the GitHub tree using a recursive listing with bounded concurrency (MANIFEST_DOWNLOAD_CONCURRENCY = 4) to produce the three manifest files. Source: src/cmd_generate.ts:48-48

See Also

• README.md — user-facing quickstart, MCP client JSON snippet, and prebuilt manifests
• official/ — prebuilt skill, agent, and design manifests maintained by the project
• community/ — community-contributed manifests
• NVIDIA SkillSpector — security scanning integrated via CI workflow since v2.0.2

Related Pages

Related topics: MCP Tools, CLI & Configuration, System Architecture & Core Components

Manifest Generation, Downloads & Security Scanning

Overview

suggest-skills ships three coordinated subsystems that operate on GitHub-hosted skill repositories: a manifest generator that crawls a GitHub tree and produces Markdown inventories, a downloader that fetches the actual SKILL.md files and their bundled assets, and a security scanning pipeline (powered by NVIDIA SkillSpector) that annotates the generated manifest with a per-skill risk score. The same binaries that run the MCP server can be invoked as a one-shot CLI in generate or download mode, and the outputs are written into the same official/ and community/ folders that the MCP server later recommends to agents. Source: README.md.

The high-level data flow is:

flowchart LR
    A[GitHub repo /tree/ URL] --> B[generate command]
    B --> C[Recursive tree listing]
    C --> D{Per directory}
    D -- contains SKILL.md --> E[skills.md]
    D -- contains DESIGN.md --> F[designs.md]
    D -- top-level .md w/ front matter --> G[agents.md]
    E --> H[SkillSpector CI scan]
    H --> I[Security Risk column]
    A --> J[download command]
    J --> K[Files + content]
    E --> L[fetch_manifest MCP tool]
    L --> M[suggest_skills recommendation]

Manifest Generation

The generator is registered as a cac subcommand and parses a single positional <url> plus an optional -r, --recursive flag. The URL is normalized through normalizeGithubRawUrl so that any github.com/.../blob/<ref>/... link resolves to its raw.githubusercontent.com counterpart before the tree walker begins. Source: src/config.ts.

Internally, generateOutputs in src/cmd_generate.ts produces three independent GeneratedDocument objects whose output kind suffixes are defined as:

Source: src/cmd_generate.ts.

Key behavioural rules implemented in the generator (all sourced from src/cmd_generate.ts and src/generate.ts):

• GitHub directory discovery uses a recursive tree listing; without --recursive only direct child directories are inspected, while root-level .md files for agents.md are still detected either way.
• SKILL.md and DESIGN.md are read with their YAML front matter; DESIGN.md is tolerant of unparseable front matter (logged and treated as markdown-only), whereas SKILL.md throws on parse errors.
• Empty generated documents — those whose rendered markdown is just the header rows — are skipped: no file is written and no overwrite prompt is shown.
• Output filenames are normalized to drop redundant type suffixes (e.g. some-skills.md rather than some-skills.skills.skills.md).
• Bundled assets are any non-SKILL.md/DESIGN.md files found in the same directory tree, listed inline (up to 3) with overflow folded into a (N more) link.

A practical invocation looks like:

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

Source: README.md.

Download System

The downloader complements the generator by retrieving the actual file contents. It is also registered through cac and accepts a positional URL plus the same -r, --recursive flag. Source: src/config.ts.

downloadGithubFolder in src/download.ts resolves the input through resolveGithubFolderUrl, which accepts both github.com/.../tree/<ref>/<path> URLs and bare raw.githubusercontent.com URLs. It then walks the tree via the GitHub Contents API and downloads up to 4 files concurrently (DOWNLOAD_CONCURRENCY). Each returned DownloadedFile carries the original relative path and the text content, leaving the calling agent free to write them to disk at any location — for example, --output=.agents/skills as shown in the example MCP config. Source: README.md.

A related helper, fetchManifestText, reads the contents of a manifest URL through the same fetch path and is used to back the fetch_manifest MCP tool. As of v1.3.0, the function consults an in-memory MANIFEST_CACHE keyed by URL — cleared via the exported clearManifestCache for tests — so repeated calls during a single session do not re-hit the network. Source: src/download.ts; release note: v1.3.0.

The download command's commit e37d398 (v2.0.1) tightened correctness by verifying that the filesystem writes actually happened after a download or generate, closing issue #119. Source: v2.0.1 release notes.

Security Scanning (SkillSpector)

The README explicitly defers security analysis to NVIDIA SkillSpector, which is wired into the repository's generate-manifests.yml CI workflow. Each skill is scanned individually and its risk score is written into the Security Risk column of the manifest, and a recommendation note is appended in v2.0.5. Source: README.md; release notes v2.0.2, v2.0.3, v2.0.5.

The manifest scan report was reworked in v2.0.3 into a bullet-list format and split into *Advisory* and *Dangerous* skill tiers in v2.0.5, giving reviewers a clearer separation between skills that should be flagged and skills that should be blocked. The most recent bug fix (v2.0.6) ensures that empty DESIGN.md entries discovered by the generator are skipped and logged rather than producing a stub row. Source: v2.0.3, v2.0.5, v2.0.6 release notes.

Note: the project itself emphasizes that the tool "doesn't provide security checks" in the host environment — risk assessment only happens in CI, not in the MCP server at runtime. Source: README.md.

Tool & Transport Integration

The generated manifests are not just static files: the MCP server exposes fetch_manifest, download_skill, and suggest_skills tools whose string identifiers are constants in src/constants.ts. suggest_skills builds a templated instruction string from config.sourceUrls (or a single manifestUrl override) using buildSuggestionResponse, which substitutes the manifest list and output directory before handing the prompt to the model. Source: src/suggest.ts; src/config.ts.

Default manifest sources can be supplied either through CLI args or the SUGGEST_SKILLS_MANIFEST_URLS environment variable, the latter being the recommended path for MCP host configuration. The v2.0.0 release removed the deprecated --manifest-urls CLI option, leaving the environment variable and per-call tool argument as the supported entry points. Source: v2.0.0 release notes.

See Also

• MCP server runtime and configuration
• Suggest Skills prompt template
• SkillSpector security workflow
• Official and community manifests

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/sator-imaging/suggest-skills

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/sator-imaging/suggest-skills

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/sator-imaging/suggest-skills

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/sator-imaging/suggest-skills

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/sator-imaging/suggest-skills

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/sator-imaging/suggest-skills

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/sator-imaging/suggest-skills

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.6 - github / github_release
• v2.0.5 - github / github_release
• v2.0.4 - github / github_release
• v2.0.3 - github / github_release
• v2.0.2 - github / github_release
• v2.0.1 - github / github_release
• v2.0.0 - github / github_release
• v1.3.1 - github / github_release
• v1.3.0 - github / github_release
• v1.2.1 - github / github_release
• Configuration risk requires verification - GitHub / issue