项目概述

suggest-skills 的核心功能是帮助 AI Agent 智能地发现和推荐可用的技能扩展包。用户可以通过配置技能清单（manifest）URL，系统会自动扫描本地已安装的技能，并与远程清单进行对比，最终呈现可用的技能建议列表。

资料来源：README.md

主要特性

资料来源：README.md

技术栈

项目采用现代 TypeScript 技术栈构建，主要依赖包括：

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "bun": "latest"
  }
}

资料来源：package.json

架构设计

整体架构

graph TD
    A[Config 配置] --> B[MCP 工具注册]
    B --> C[stdio 传输模式]
    B --> D[HTTP 传输模式]
    
    E[CLI generate 命令] --> F[GitHub 目录扫描]
    F --> G[生成 manifest markdown]
    
    H[GitHub URL 规范化] --> I[文件夹下载]
    I --> F

项目架构分为两个主要入口：

1. MCP 服务器模式：通过 Config 配置驱动的 MCP 工具服务
2. CLI 生成模式：命令行工具用于扫描 GitHub 仓库生成技能清单

资料来源：README.md

模块职责

资料来源：src/download.ts, src/generate.ts, src/cmd_generate.ts

MCP 工具接口

suggest_skills

主动建议可用技能的主工具。

返回说明：生成一条指令负载，指导 Agent 如何获取可用技能列表、对比本地与远程能力、以及呈现建议。

资料来源：README.md

fetch_manifest

获取指定清单文件内容。

返回内容：清单文件的完整文本内容。

资料来源：README.md

download_skill

下载指定 GitHub 文件夹中的所有文件。

返回内容：文件夹中每个文件的路径、UTF-8 文本内容。符号链接会被解析并递归下载。

资料来源：README.md, src/download.ts

下载流程实现

GitHub API 调用

项目使用 GitHub Contents API 和 Git Trees API 来获取仓库内容：

sequenceDiagram
    参与者 A as 用户请求
    参与者 G as GitHub API
    参与者 L as 本地处理
    
    A->>G: 请求目录内容
    G-->>L: 返回 tree 结构
    L->>L: 解析路径并过滤
    L->>G: 获取文件下载 URL
    G-->>A: 返回文件内容

资料来源：src/download.ts

路径解析逻辑

下载模块的核心路径处理逻辑位于 buildContentsApiUrl 和 buildTreeApiUrl 函数中：

function buildContentsApiUrl(location: GithubDirectoryLocation): string {
  const pathSuffix = location.path
    .split("/")
    .filter(Boolean)
    .map((part) => encodeURIComponent(part))
    .join("/");
  // 构建 API 路径并添加 ref 参数
}

关键处理步骤：

1. 过滤空路径段
2. 对每个路径段进行 URL 编码
3. 拼接为标准 GitHub API 路径
4. 设置 ref 参数指定分支/提交

资料来源：src/download.ts

清单生成功能

generate 命令工作流

graph LR
    A[GitHub URL] --> B[目录扫描]
    B --> C[识别 SKILL.md]
    B --> D[识别 DESIGN.md]
    B --> E[收集资产文件]
    
    C --> F[生成 skills.md]
    D --> G[生成 designs.md]
    E --> F
    E --> G

生成模式下，系统会：

1. 递归扫描 GitHub 目录结构
2. 识别包含 SKILL.md 的技能目录
3. 识别包含 DESIGN.md 的设计目录
4. 收集目录中的其他资产文件
5. 生成格式化的 Markdown 清单文件

资料来源：src/generate.ts, README.md

生成选项

资料来源：README.md

输出文件类型

资料来源：README.md

配置管理

环境变量配置

清单 URL 支持三种格式：

资料来源：README.md

启动模式

#### stdio 模式

标准输入输出模式，适合本地集成：

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

#### HTTP 服务器模式

提供 HTTP API 端点，适合远程访问：

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

资料来源：README.md

代码规范

项目遵循以下编码标准：

资料来源：README.md

使用示例

快速开始

``bash export SUGGEST_SKILLS_MANIFEST_URLS='["https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md"]' ``

1. 配置环境变量：

``bash npx suggest-skills server --port 3100 ``

1. 运行 MCP 服务器：

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

1. 生成技能清单：

递归扫描示例

生成包含子目录的完整清单：

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

这会生成以下文件：

• <owner>.<repo>.<path>.skills.md
• <owner>.<repo>.<path>.designs.md

资料来源：README.md

相关资源

系统架构

整体架构图

graph TD
    subgraph 配置层
        A[环境变量配置] --> B[Config 验证模块]
        B --> C[ConfigError 异常处理]
    end
    
    subgraph 核心功能层
        D[MCP 工具注册] --> E[suggest_skills]
        D --> F[fetch_manifest]
        D --> G[download_skill]
    end
    
    subgraph 传输层
        H[stdio 传输] 
        I[HTTP 传输]
    end
    
    subgraph GitHub 交互层
        J[目录扫描] --> K[SKILL.md 发现]
        J --> L[DESIGN.md 发现]
        J --> M[manifest 生成]
    end
    
    B --> D
    E --> J
    F --> M
    G --> J
    D --> H
    D --> I

技术栈

资料来源：README.md:技术栈

MCP 工具集

项目提供三个核心 MCP 工具，供 AI 代理调用以实现技能管理功能。

工具功能总览

suggest_skills 工具

该工具是系统的核心入口点，负责生成指令负载，指导 AI 代理完成以下任务：

• 从配置的 manifest 文件获取可用技能列表
• 扫描本地已安装的技能
• 对比远程与本地能力差异
• 在用户请求前不执行任何安装操作

graph LR
    A[调用 suggest_skills] --> B{是否指定 manifestUrl?}
    B -->|是| C[使用指定 URL]
    B -->|否| D[使用环境变量配置的默认 URL]
    C --> E[生成指令负载]
    D --> E
    E --> F[返回技能发现/推荐指导]

fetch_manifest 工具

用于获取远程技能清单的原始文本内容，支持自定义技能仓库的 manifest 文件获取。

download_skill 工具

该工具实现 GitHub 目录的递归下载功能，支持以下特性：

• 接收标准 GitHub 树形 URL 格式：https://github.com/<owner>/<repo>/tree/<ref>/<path>
• 返回文件夹内所有文件及其相对路径
• 自动处理文件 symlink（当 GitHub 提供 download_url 时）
• 解析仓库相对目录 symlink 并递归下载

资料来源：README.md:MCP Tools

技能清单生成

生成工作流程

graph TD
    A[CLI: npx suggest-skills generate] --> B[接收 GitHub URL]
    B --> C{是否指定 --recursive?}
    C -->|是| D[递归扫描目录树]
    C -->|否| E[扫描当前层级]
    D --> F[发现 SKILL.md 文件]
    E --> F
    F --> G[发现 DESIGN.md 文件]
    G --> H[汇总同目录资产文件]
    H --> I[生成清单文件]
    
    I --> J[.skills.md]
    I --> K[.designs.md]
    I --> L[.agents.md]

生成规则

输出文件类型

资料来源：README.md:Generate a Manifest 资料来源：src/generate.ts:SKILL.md/DESIGN.md 发现逻辑

配置管理

环境变量配置

SUGGEST_SKILLS_MANIFEST_URLS 支持三种格式：

• JSON 数组：["url1", "url2"]
• 逗号分隔字符串：url1,url2
• 换行分隔字符串：url1\nurl2

注意：GitHub blob URL 会自动转换为 raw.githubusercontent.com URL。

资料来源：README.md:Environment Variables

配置验证

系统通过 ConfigError 异常类实现显式配置验证，确保：

• 至少配置一个 manifest URL
• URL 格式正确
• 环境变量解析成功

stateDiagram-v2
    [*] --> 加载环境变量
    加载环境变量 --> 验证配置
    验证配置 --> 配置有效: 通过
    验证配置 --> ConfigError: 失败
    配置有效 --> MCP 工具注册
    ConfigError --> [*]

运行模式

stdio 模式

适用于本地集成和管道通信场景：

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

HTTP 模式

适用于分布式部署和远程服务场景：

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

资料来源：README.md:Run in stdio Mode 资料来源：README.md:Run in HTTP Mode

GitHub API 交互

API 端点构建

项目封装了多个 GitHub API URL 构建函数：

目录扫描数据结构

interface ContentEntry {
  path: string;           // 文件相对路径
  download_url: string | null;  // 下载 URL（文件）或 null（目录）
  type: "file" | "dir";   // 条目类型
}

路径解析规则

1. 解析 GitHub 目录位置信息（owner、repo、ref、path）
2. 将相对路径与基础路径拼接
3. 去除前导斜杠确保路径一致性
4. 递归处理树形结构

graph LR
    A[GitHub Tree API 响应] --> B[遍历 entries]
    B --> C{entry.type === 'tree'?}
    C -->|是| D[创建 dir 条目]
    C -->|否| E[entry.type === 'blob'?]
    E -->|是| F[构建 download_url]
    F --> G[创建 file 条目]
    E -->|否| H[跳过]
    D --> I[返回 ContentEntry 数组]
    G --> I

资料来源：src/download.ts:ContentEntry 类型定义 资料来源：src/download.ts:buildContentsApiUrl 函数

CLI 选项

默认安装目录：.agents/skills

代码组织规范

项目遵循以下实现模式：

资料来源：README.md:Coding Standards

与官方技能仓库集成

项目内置支持从主流技能仓库生成清单和下载技能：

Anthropic 官方技能

包含 40+ 个预构建技能，覆盖文档协作、Word 文档处理、PDF 操作、Figma 设计集成、Web 应用测试等领域。

OpenAI 精选技能

包含 Notion 集成、Linear 项目管理、PDF 处理、Jupyter 笔记本、Figma 协作、Playwright 自动化测试、Vercel/Netlify 部署等企业级工具。

社区技能

汇集来自 ComposioHQ 等社区的精选技能，包括主题工厂、Twitter 算法优化、YouTube 下载器等实用工具。

资料来源：官方 Skills 清单 资料来源：OpenAI Skills 清单 资料来源：社区 Skills 清单

概述

suggest-skills 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理工具，旨在帮助 AI Agent 智能地发现、推荐和安装来自各种来源的技能扩展包。 资料来源：README.md

该项目的核心价值在于：将分散在不同 GitHub 仓库中的技能清单（Manifest）聚合起来，为 Agent 提供统一的技能发现和安装接口，而无需预先安装任何内容。

技术栈

资料来源：README.md

概述

suggest-skills 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理系统。该项目允许 AI Agent 发现、扫描并推荐可用的技能（Skills），同时支持从 GitHub 下载技能资源。项目的核心架构围绕 MCP 协议展开，通过标准化的工具接口实现远程与本地技能的能力对比与展示。

资料来源：README.md

技术栈

资料来源：README.md

整体架构

项目采用分层架构设计，核心流程为：配置层 → MCP 工具注册 → 传输层（stdio 或 HTTP）。同时提供独立的 CLI 工具用于生成技能清单。

graph TD
    A[配置文件] --> B[MCP 工具注册]
    B --> C[stdio 传输模式]
    B --> D[HTTP 传输模式]
    E[CLI generate] --> F[GitHub 目录扫描]
    F --> G[生成 Manifest Markdown]
    H[下载技能] --> I[download_skill 工具]
    J[推荐技能] --> K[suggest_skills 工具]

资料来源：README.md

目录结构

源码目录 (`src/`)

技能清单目录

每个技能目录下应包含 SKILL.md 或 DESIGN.md 文件，用于描述技能的用途与触发条件。

资料来源：README.md

核心模块

配置模块 (`src/config.ts`)

配置模块负责验证环境变量与命令行参数，确保 MCP 服务正常运行。

关键环境变量：

配置格式：

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

GitHub blob URL 会自动转换为 raw.githubusercontent.com URL。

资料来源：README.md

GitHub 下载模块 (`src/download.ts`)

该模块封装了 GitHub API 调用，实现目录内容的递归下载。

核心 API 交互：

graph LR
    A[buildContentsApiUrl] --> B[GET /repos/{owner}/{repo}/contents/{path}]
    C[buildTreeApiUrl] --> D[GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1]

主要函数：

资料来源：src/download.ts

Manifest 生成模块 (`src/generate.ts`)

负责扫描技能目录并生成规范化的 Markdown 清单文件。

处理流程：

1. 遍历目录树，识别包含 SKILL.md 或 DESIGN.md 的目录
2. 收集同目录下的其他资源文件作为 bundled assets
3. 按目录层级组织输出

graph TD
    A[遍历目录树] --> B{文件类型判断}
    B -->|SKILL.md| C[标记为技能目录]
    B -->|DESIGN.md| D[标记为设计目录]
    B -->|其他资源| E[加入 bundled assets]
    C --> F[按层级排序输出]
    D --> F

资料来源：src/generate.ts

CLI 生成命令 (`src/cmd_generate.ts`)

实现命令行工具的 generate 子命令，支持递归扫描和自定义输出目录。

CLI 选项：

生成的输出文件类型：

资料来源：src/cmd_generate.ts

MCP 工具接口

suggest_skills

推荐可用技能的 MCP 工具，根据用户需求返回相应的技能建议。

输入参数：

返回内容： 生成指令负载，指导 Agent 如何获取、扫描、对比远程与本地技能，并展示推荐结果。

fetch_manifest

获取指定清单文件内容的工具。

输入参数：

download_skill

下载 GitHub 文件夹中的所有文件。

输入参数：

返回内容： 文件夹内每个文件的相对路径、UTF-8 文本内容及类型信息。

资料来源：README.md

传输模式

stdio 模式

适用于本地进程间通信的标准化输入输出模式。

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

HTTP 模式

适用于网络化的 MCP 客户端连接。

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

端点：

资料来源：README.md

编码规范与设计原则

项目遵循以下实现模式：

资料来源：README.md

扩展方式

贡献新技能

1. 在 community/skills/ 下创建技能目录
2. 添加 SKILL.md 文件描述技能用途与触发条件
3. 可选：添加相关资源文件作为 bundled assets

添加新的清单源

1. 在 SUGGEST_SKILLS_MANIFEST_URLS 中添加新的 URL
2. 遵循现有的 Markdown 清单格式

扩展 MCP 工具

新工具应：

• 在 src/ 下创建独立的模块文件
• 使用 Zod 定义输入输出 Schema
• 在 index.ts 中注册到 MCP 服务

概述

MCP 工具是 suggest-skills 项目实现的核心功能模块，基于 Model Context Protocol (MCP) 标准提供技能建议、清单获取和技能下载能力。该模块作为 MCP 服务器运行，支持 stdio 和 HTTP 两种传输模式，使 AI 代理能够动态发现和推荐可用技能。

MCP 工具的主要职责包括：

• 从配置的清单 URL 获取远程技能目录
• 扫描本地已安装的技能
• 对比远程与本地能力差异
• 向用户展示技能建议列表
• 下载指定 GitHub 文件夹中的所有文件

资料来源：README.md

架构概览

Config -> MCP 工具注册 -> stdio 或 HTTP 传输

项目采用分层架构：

• 配置层：环境变量和命令行参数解析
• 工具层：三个核心 MCP 工具实现
• 传输层：stdio 和 HTTP 两种通信协议支持
• GitHub 交互层：仓库扫描和文件下载

技术栈：Bun、TypeScript、@modelcontextprotocol/sdk、Zod

资料来源：README.md:89-94

核心工具列表

资料来源：README.md:53-73

suggest_skills 工具

功能说明

suggest_skills 是默认的技能推荐工具，返回一个生成的指令负载。该负载指示代理如何：

1. 从配置的清单中获取可用技能
2. 扫描本地已安装的技能
3. 对比远程与本地的能力差异
4. 展示建议而不自动安装

参数定义

返回值

返回包含以下步骤的指令负载：

• 获取清单中的技能列表
• 本地技能扫描
• 差异对比分析
• 用户建议展示（仅在请求时安装）

资料来源：src/suggest.ts

fetch_manifest 工具

功能说明

fetch_manifest 工具接受一个清单 URL 参数，返回该清单的完整文本内容。用于获取远程技能目录的详细描述。

参数定义

典型使用场景

• 获取第三方技能仓库的清单
• 动态更新本地缓存的技能列表
• 跨仓库技能发现

download_skill 工具

功能说明

download_skill 工具用于下载 GitHub 文件夹中的所有文件，返回每个文件的相对路径、UTF-8 文本内容和符号链接信息。

参数定义

返回数据结构

GitHub URL 解析

工具内部通过以下步骤解析 GitHub 目录位置：

interface GithubDirectoryLocation {
  owner: string;  // 仓库所有者
  repo: string;   // 仓库名称
  ref: string;     // 分支/标签/提交 SHA
  path: string;   // 目录路径
}

资料来源：src/download.ts:1-50

工作流程图

graph TD
    A[启动 MCP 服务器] --> B{传输模式}
    B -->|stdio| C[标准输入输出]
    B -->|HTTP| D[HTTP 端点 /mcp]
    C --> E[注册 MCP 工具]
    D --> E
    E --> F[suggest_skills]
    E --> G[fetch_manifest]
    E --> G --> H[获取清单文本]
    E --> I[download_skill]
    I --> J[解析 GitHub URL]
    J --> K[调用 GitHub Contents API]
    K --> L[递归获取目录树]
    L --> M[构建下载条目列表]
    M --> N[返回文件内容]

配置方式

环境变量

SUGGEST_SKILLS_MANIFEST_URLS 支持以下格式：

• JSON 数组：["https://example.com/manifest.md"]
• 逗号分隔字符串："url1,url2,url3"
• 换行分隔字符串："url1\nurl2\nurl3"

CLI 选项

默认输出目录：.agents/skills

资料来源：src/config.ts:1-50

HTTP 模式

HTTP 服务器提供以下端点：

默认端口：3100

启动命令

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

GitHub API 集成

API 端点

URL 转换

GitHub blob URL 自动转换为 raw.githubusercontent.com URL：

function normalizeGithubRawUrl(url: string): string | null {
  // 将 github.com/blob/ 转换为 raw.githubusercontent.com/
}

资料来源：src/download.ts:40-70

类型定义

ContentEntry

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

CliRuntimeMode

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

Config

interface Config {
  manifestUrls: string[];
  outputDirectory: string;
  githubPat?: string;
}

清单文件格式

清单文件为 Markdown 格式，支持以下结构：

| 技能名称 | 描述 | 文件列表 |
|---------|------|---------|
| [skill-name](链接) | 功能说明 | `file1.md`, `assets/` |

生成模式自动扫描包含 SKILL.md 或 DESIGN.md 的目录。

资料来源：src/generate.ts:1-80

最佳实践

1. 清单 URL 配置

建议使用多个清单源以覆盖更广泛的技能库：

SUGGEST_SKILLS_MANIFEST_URLS='[
  "https://raw.githubusercontent.com/anthropics/skills/main/README.md",
  "https://raw.githubusercontent.com/openai/skills/main/README.md",
  "https://raw.githubusercontent.com/sator-imaging/suggest-skills/main/README.md"
]'

2. 递归下载

对于包含子目录的技能文件夹，使用 --recursive 选项确保完整下载：

npx suggest-skills download --recursive \
  https://github.com/owner/repo/tree/main/skills/my-skill

3. GitHub 认证

当访问私有仓库或需要更高 API 限额时，配置 GITHUB_PAT：

GITHUB_PAT=ghp_xxx npx suggest-skills fetch_manifest

相关文档

• 官方技能目录
• 社区技能
• 生成清单命令
• 下载技能命令

概述

suggest-skills 项目实现了 MCP (Model Context Protocol) 服务器，支持两种传输模式用于与 AI 代理进行通信。这两种模式分别为 stdio 模式 和 HTTP 模式，它们共享相同的核心功能和 MCP 工具集，仅在通信机制上有所不同。

传输模式的选择直接影响工具调用方与应用服务器的交互方式：

• stdio 模式：适用于本地进程通信，通过标准输入/输出流传递 JSON-RPC 消息
• HTTP 模式：适用于网络远程调用，通过 HTTP REST API 提供 MCP 端点

资料来源：README.md

架构设计

传输层抽象

项目采用传输层抽象设计，将核心业务逻辑与通信机制分离。配置层负责解析 CLI 参数并确定运行时模式，随后将控制权委托给对应的传输处理器。

graph TD
    A[CLI 入口] --> B[配置解析]
    B --> C{运行时模式}
    C -->|stdio| D[stdio.ts]
    C -->|server| E[http.ts]
    D --> F[MCP 工具注册]
    E --> F
    F --> G[核心业务逻辑]
    G --> H[suggest_skills]
    G --> I[fetch_manifest]
    G --> J[download_skill]

资料来源：src/config.ts

运行时模式类型

CliRuntimeMode 联合类型定义了所有支持的运行时变体：

资料来源：src/config.ts:1-50

stdio 模式

工作原理

stdio 模式是 MCP 协议的传统实现方式，服务器通过标准输入接收 JSON-RPC 请求，并通过标准输出返回响应消息。此模式无需网络配置，非常适合与本地 AI 代理进程集成。

启动方式

stdio 模式作为默认模式运行，当用户未指定任何子命令时自动激活：

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

环境变量 SUGGEST_SKILLS_MANIFEST_URLS 为必需配置，必须包含至少一个技能清单 URL。

特性

• 零网络依赖：无需开放端口，完全在本地运行
• 进程隔离：每个会话创建独立进程
• 低延迟：直接内存通信，无网络开销
• 标准化协议：完全兼容 MCP JSON-RPC 规范

资料来源：README.md

HTTP 模式

工作原理

HTTP 模式启动一个基于 Streamable HTTP 的 MCP 服务器，支持远程调用和持久化连接。此模式适用于需要跨网络访问 MCP 工具的场景。

端点配置

启动方式

使用 server 子命令启动 HTTP 服务器：

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

端口配置

通过 --port 参数指定监听端口，默认情况下服务器绑定至 0.0.0.0 接受所有网络接口连接。

特性

• 远程访问：支持跨网络调用 MCP 工具
• 持久连接：支持流式响应和连接复用
• 健康监控：内置健康检查端点便于运维监控
• REST 兼容：基于标准 HTTP 协议，易于集成

资料来源：README.md

配置管理

环境变量

清单 URL 格式

清单 URL 支持多种格式：

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

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

GitHub blob URL 会自动转换为 raw.githubusercontent.com URL。

资料来源：README.md

CLI 命令结构

命令速查表

全局选项

• -o, --output <dir>：设置技能安装输出目录，默认为 .agents/skills

生成模式选项

• -r, --recursive：启用递归扫描子目录
• --url：指定 GitHub 仓库路径

服务器模式选项

• --port <port>：指定 HTTP 服务器监听端口

资料来源：src/config.ts

MCP 工具集

无论采用哪种传输模式，以下 MCP 工具均可用：

suggest_skills

返回生成的指令负载，指导代理如何：

• 获取已配置清单中的可用技能
• 扫描本地已安装技能
• 比较远程与本地能力
• 在用户请求前呈现建议而不安装任何内容

参数：manifestUrl (可选) - 覆盖默认配置的清单 URL

fetch_manifest

获取指定清单 URL 的文本内容。

参数：manifestUrl - 清单 URL

download_skill

下载 GitHub 文件夹中的所有文件。

参数：url - GitHub 文件夹 URL，格式为 https://github.com/<owner>/<repo>/tree/<ref>/<path>

返回每个文件包含：

• 相对于请求文件夹的路径
• UTF-8 文本内容
• 文件 symlink 的目标内容

资料来源：README.md

模式选择指南

graph TD
    A[开始] --> B{调用场景?}
    B -->|本地 AI 代理| C[stdio 模式]
    B -->|远程服务| D[HTTP 模式]
    B -->|生成清单| E[generate 模式]
    B -->|批量下载| F[download 模式]
    C --> G[低延迟隔离环境]
    D --> H[跨网络访问]
    E --> I[生成 markdown 文档]
    F --> J[获取技能文件]

选择建议

技术栈

项目使用的核心技术：

资料来源：README.md

最佳实践

环境配置

# 生产环境建议
export GITHUB_PAT="your_personal_access_token"
export SUGGEST_SKILLS_MANIFEST_URLS='["https://raw.githubusercontent.com/anthropics/skills/main/skills/README.md"]'

安全考量

• HTTP 模式部署时应配置 TLS 终止
• GitHub PAT 应存储在安全密钥管理系统中
• 避免在日志中输出敏感配置信息

性能优化

• stdio 模式适合高频低延迟场景
• HTTP 模式支持连接池和请求批处理
• 大型仓库建议使用递归模式以获取完整技能树

概述

Generate 命令是 suggest-skills 工具的核心功能之一，用于从 GitHub 仓库中扫描技能目录并生成标准化的 Markdown 清单文件。该命令通过递归扫描 GitHub 目录结构，自动发现包含 SKILL.md、DESIGN.md 的技能目录，并将其转换为可读的 Markdown 表格格式。

Generate 命令的主要职责包括：

• 扫描指定的 GitHub 仓库或目录路径
• 递归发现技能定义文件
• 收集每个技能的元数据（名称、描述、关联资产）
• 生成格式化的 Markdown 清单文件
• 支持可选的递归扫描模式

命令行接口

基本语法

npx suggest-skills generate <github-url>

递归扫描模式

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

参数说明

工作流程

graph TD
    A[用户执行 generate 命令] --> B[解析 GitHub URL]
    B --> C{是否为递归模式?}
    C -->|是| D[使用 Tree API 递归获取目录结构]
    C -->|否| E[使用 Contents API 获取单层目录]
    D --> F[扫描 SKILL.md 和 DESIGN.md 文件]
    E --> F
    F --> G[收集技能条目和资产信息]
    G --> H[格式化 Markdown 表格]
    H --> I[生成输出文件]
    I --> J[写入 <owner>.<repo>.<path>.skills.md]
    I --> K[写入 <owner>.<repo>.<path>.designs.md]
    I --> L[写入 <owner>.<repo>.<path>.agents.md]

输出文件

执行 generate 命令后，会在当前工作目录生成以下文件：

生成的 Markdown 格式

| Name | Description |
| -----|-------------|
| [skill-name](url) | skill description |

当启用资产包含选项时，格式扩展为：

| Name | Description | Bundled Assets |
| -----|-------------|----------------|
| [skill-name](url) | description | LICENSE.txt, scripts (5 files) |

源码架构

核心模块职责

运行时模式定义

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

资料来源：src/config.ts:32-38

表格格式化流程

graph LR
    A[Entry 数据] --> B[formatRow 函数]
    B --> C{includeAssets?}
    C -->|是| D[格式化资产列]
    C -->|否| E[仅输出名称和描述]
    D --> F[escapeTableCell 转义特殊字符]
    E --> F
    F --> G[拼接 Markdown 行]
    G --> H[生成完整表格]

表格单元格格式化

Generate 命令使用 escapeTableCell 函数处理单元格内容，防止 Markdown 表格解析错误。

转义规则

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

资料来源：src/cmd_generate.ts:75-77

资产打包格式

当技能目录包含额外文件时，Generate 命令会将这些文件列为"关联资产"。

资产显示格式

内联资产数量限制

const BUNDLED_ASSETS_INLINE_MAX_ITEMS = 3;

当资产数量超过 3 个时，Generate 命令会切换为计数显示模式，避免表格过宽。

GitHub URL 处理

URL 规范化

Generate 命令支持多种 GitHub URL 格式：

API 端点构建

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

资料来源：src/download.ts:85-98

空输出处理

Generate 命令实现了智能的空输出检测机制，避免生成无意义的清单文件。

空文档判定

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

资料来源：src/cmd_generate.ts:64-68

当检测到空输出时：

• 不写入任何文件
• 不显示覆盖确认提示
• 静默跳过该类型清单

配置集成

Generate 命令可以通过环境变量进行配置：

环境变量

Manifest URL 格式

# JSON 数组格式
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]'

# 逗号分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='url1,url2,url3'

# 换行分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='url1
url2'

最佳实践

推荐使用场景

1. 初始化新仓库：首次设置技能目录时生成清单
2. 同步更新：每次技能更新后重新生成以保持文档最新
3. 多仓库管理：使用递归模式扫描组织下的所有技能

性能注意事项

GitHub API 限制

• 未认证请求：每小时 60 次
• 认证请求（使用 GITHUB_PAT）：每小时 5000 次

对于大型仓库或频繁使用场景，建议配置 GITHUB_PAT 环境变量。

完整使用示例

示例 1：扫描官方技能库

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

输出文件：

• anthropics.skills.skills.md
• anthropics.skills.designs.md
• anthropics.skills.agents.md

示例 2：递归扫描社区技能

SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]' \
npx suggest-skills generate \
  --recursive \
  https://github.com/ComposioHQ/awesome-claude-skills/tree/master

示例 3：集成到 CI/CD

# .github/workflows/generate-skills.yml
name: Generate Skills Manifest
on:
  schedule:
    - cron: '0 0 * * *'  # 每日执行
  push:
    branches:
      - main

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate skills manifest
        env:
          GITHUB_PAT: ${{ secrets.GITHUB_PAT }}
          SUGGEST_SKILLS_MANIFEST_URLS: '["https://raw.githubusercontent.com/anthropics/skills/main/skills-index.json"]'
        run: npx suggest-skills generate --recursive https://github.com/anthropics/skills/tree/main/skills

相关命令

概述

server 命令是 suggest-skills CLI 工具的核心运行模式之一，用于启动一个基于 HTTP 协议的 MCP（Model Context Protocol）流式服务器。该服务器提供了技能（Skills）发现、清单获取和技能下载等核心功能，使 AI 代理能够在运行时动态获取和推荐可用的技能扩展。

Server 命令的主要职责包括：

• 注册 MCP 工具接口
• 提供 RESTful HTTP 端点
• 处理技能清单的获取与解析
• 支持技能目录的下载功能

资料来源：README.md:1-20

架构设计

技术栈

Server 命令基于以下技术构建：

资料来源：README.md:89-96

项目架构

Config -> MCP tool registration -> stdio or HTTP transport

CLI generate -> GitHub directory scan -> manifest markdown file
             \-> GitHub URL normalization / folder download

整体架构遵循配置驱动、工具注册、传输层分离的设计模式。HTTP 传输作为独立的传输层实现，与 stdio 模式共享核心业务逻辑。

资料来源：README.md:98-104

命令行接口

基本用法

npx suggest-skills server --port <端口号>

端口配置

配置示例：

# 启动服务器并指定端口
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
  npx suggest-skills server --port 3100

资料来源：src/config.ts:30-33

HTTP 端点

端点列表

服务地址

• MCP 端点: http://localhost:<端口>/mcp
• 健康检查: http://localhost:<端口>/health

默认配置下：

• MCP 端点: http://localhost:3100/mcp
• 健康检查: http://localhost:3100/health

资料来源：README.md:76-77

MCP 工具

Server 命令注册了以下 MCP 工具供 AI 代理调用：

suggest_skills

获取技能建议的工具，用于告知 AI 代理如何：

• 从配置的清单中获取可用技能
• 扫描本地已安装的技能
• 比较远程与本地能力
• 在用户请求前仅展示建议而不实际安装

参数:

资料来源：README.md:80-92

fetch_manifest

获取指定清单 URL 的文本内容。

参数:

资料来源：README.md:94-97

download_skill

下载 GitHub 文件夹中的所有文件。

参数:

返回内容:

• 文件相对路径
• UTF-8 编码的文本内容
• GitHub 提供的 symlink 目标内容
• 仓库相对目录 symlink 自动解析并递归下载

资料来源：README.md:99-112

数据流程

技能下载流程

graph TD
    A[download_skill 工具调用] --> B[解析 GitHub URL]
    B --> C[构建 Contents API 请求]
    C --> D[获取仓库 Tree SHA]
    D --> E[递归获取文件树]
    E --> F[处理 symlink 解析]
    F --> G[构建下载 URL]
    G --> H[返回文件内容列表]
    
    I[buildGithubRawUrl] --> G
    J[buildTreeApiUrl] --> D

清单生成流程

graph TD
    A[generate 命令] --> B[扫描 GitHub 目录]
    B --> C[递归发现 SKILL.md]
    C --> D[收集同目录资产文件]
    D --> E[构建 Markdown 表格]
    E --> F[输出清单文件]
    
    G[normalizeGithubRawUrl] --> A

资料来源：src/download.ts:1-50, src/generate.ts:1-80

环境配置

必需环境变量

支持的格式:

• JSON 数组: ["url1", "url2"]
• 逗号分隔字符串: "url1,url2"
• 换行分隔字符串: "url1\nurl2"

可选环境变量

URL 自动转换

GitHub blob URLs 会自动转换为 raw.githubusercontent.com URLs。

资料来源：README.md:120-138

代码实现

命令注册

Server 命令通过 cac CLI 框架注册：

cli
  .command("server [...args]", "Run the streamable HTTP server")
  .option("--port <port>", "Port number")
  .action(actions.onServer);

资料来源：src/config.ts:30-33

运行时模式

Server 命令解析后生成以下运行时配置：

{
  kind: "server",
  port: number,
  config: {
    manifestUrls: string[],
    githubToken?: string
  }
}

传输模式对比

资料来源：README.md:142-157

最佳实践

生产环境部署

1. 配置清单 URL: 确保 SUGGEST_SKILLS_MANIFEST_URLS 包含所有必需的技能清单
2. 使用 GitHub Token: 通过 GITHUB_PAT 提升 API 请求频率限制
3. 健康检查: 定期调用 /health 端点验证服务状态

调试建议

• 使用 --port 参数指定非默认端口避免冲突
• 查看服务器日志确认 MCP 工具注册状态
• 使用 curl http://localhost:<port>/health 快速验证服务

相关命令

资料来源：src/config.ts:20-35

概述

suggest-skills 是一个基于 Model Context Protocol (MCP) 的技能建议工具，用于从 GitHub 仓库中发现、管理和推荐 AI 助手技能。该项目支持三种运行时模式：stdio 模式、HTTP 服务模式和生成模式，通过环境变量和命令行参数进行灵活配置。 资料来源：README.md:1-50

核心配置架构

graph TD
    A[环境变量配置] --> B[CLI 参数解析]
    B --> C{运行时模式}
    C -->|stdio| D[MCP stdio 传输]
    C -->|server| E[MCP HTTP 服务]
    C -->|generate| F[Manifest 生成器]
    
    A1[`SUGGEST_SKILLS_MANIFEST_URLS`] --> A
    A2[`GITHUB_PAT`] --> A
    B1[`-o, --output`] --> B
    B2[`-r, --recursive`] --> B
    B3[`--port`] --> B

环境变量配置

必需配置

SUGGEST_SKILLS_MANIFEST_URLS 是必需的配置文件，必须包含至少一个有效的清单 URL。支持的格式如下：

# JSON 数组格式
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]'

# 逗号分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'

# 换行分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md
https://example.com/manifest2.md'

GitHub blob URL 会自动转换为 raw.githubusercontent.com URL。 资料来源：README.md:70-90

可选配置

命令行接口配置

全局选项

输出目录指定安装的技能文件存放位置，相对路径相对于当前工作目录。 资料来源：src/config.ts:1-50

子命令配置

#### generate 命令

npx suggest-skills generate <github-url> [--recursive, -r]

生成模式会扫描指定 GitHub 路径下的所有技能目录，并生成以下文件：

• <owner>.<repo>[.<path>].skills.md - 包含 SKILL.md 的技能目录清单
• <owner>.<repo>[.<path>].designs.md - 包含 DESIGN.md 的设计目录清单
• <owner>.<repo>[.<path>].agents.md - 平面顶级 Markdown 文件中的代理清单

空生成的输出会被跳过，不会覆盖现有文件。 资料来源：README.md:40-65

#### download 命令

npx suggest-skills download <url> [--recursive, -r]

下载技能、代理和设计文件到当前目录。使用 GitHub Contents API 递归获取文件内容。 资料来源：src/download.ts:1-40

#### server 命令

npx suggest-skills server [--port <number>]

HTTP 服务提供两个端点：

• http://localhost:<port>/mcp - MCP 协议端点
• http://localhost:<port>/health - 健康检查端点

graph LR
    A[客户端] -->|HTTP 请求| B[MCP 端点 /mcp]
    A -->|健康检查| C[Health 端点 /health]
    B --> D[技能清单处理]
    C --> E[服务状态返回]

#### stdio 模式（默认）

当不指定任何子命令时，工具以 stdio 模式运行，作为 MCP 服务器通过标准输入输出通信：

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

配置验证机制

ConfigError 异常处理

项目通过 ConfigError 类进行显式配置验证，任何配置错误都会抛出该异常并终止程序执行。这确保了配置问题在启动阶段就能被发现。 资料来源：src/config.ts:1-20

运行时模式解析

配置解析流程如下：

graph TD
    A[解析 process.argv] --> B[解析环境变量]
    B --> C{命令类型判断}
    C -->|generate| D[设置 generate 运行时模式]
    C -->|download| E[设置 download 运行时模式]
    C -->|server| F[设置 server 运行时模式]
    C -->|无命令| G[设置 stdio 运行时模式]
    
    D --> H[构建配置对象]
    E --> H
    F --> H
    G --> H

每个运行时模式包含以下配置属性：

MCP 工具配置

suggest_skills 工具

核心建议工具，接受可选的 manifestUrl 参数覆盖默认配置。返回生成的指令载荷，指导代理如何：

• 从配置的清单获取可用技能
• 扫描本地安装的技能
• 比较远程和本地能力
• 在请求安装前呈现建议

fetch_manifest 工具

接受清单 URL 并返回其文本内容。

download_skill 工具

接受 GitHub 文件夹 URL 格式：

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

返回文件夹中的每个文件，包含相对路径、UTF-8 文本内容和符号链接信息。 资料来源：README.md:100-130

清单文件格式

技能清单结构

清单文件采用 Markdown 表格格式，每行包含技能名称（链接）、描述和捆绑资源：

| Name | Description | Bundled Assets |
|------|-------------|----------------|
| [skill-name](url) | Description text | `file1.txt`, `dir/` (3 files) |

Manifest 加载流程

sequenceDiagram
    participant CLI as CLI 工具
    participant Config as 配置模块
    participant Manifest as 清单 URL
    participant MCP as MCP 服务器
    
    CLI->>Config: 解析环境变量
    Config->>Manifest: 获取清单内容
    Manifest-->>Config: 返回 Markdown
    Config->>MCP: 注册工具和资源
    MCP->>CLI: 服务就绪

常见配置场景

场景一：本地开发环境

# 设置清单源
export SUGGEST_SKILLS_MANIFEST_URLS='["https://raw.githubusercontent.com/anthropics/skills/main/official/skills.skills.md"]'

# 以 stdio 模式运行
npx suggest-skills

场景二：HTTP 服务部署

# 设置清单源（多源）
export SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest1.md","https://example.com/manifest2.md"]'

# 自定义端口
npx suggest-skills server --port 8080

场景三：从 GitHub 生成清单

# 递归扫描官方技能
npx suggest-skills generate https://github.com/anthropics/skills/tree/main/skills --recursive

# 单层扫描
npx suggest-skills generate https://github.com/anthropics/skills/tree/main/official/skills

技术栈配置依赖

项目使用以下技术栈构建，所有配置都围绕这些核心依赖展开：

配置最佳实践

1. 环境变量优先：优先通过环境变量配置清单 URL，避免硬编码
2. 使用认证令牌：生产环境建议配置 GITHUB_PAT 以提高 API 限制
3. 指定输出目录：使用 -o 选项明确指定技能安装位置
4. 递归扫描谨慎使用：大仓库递归扫描会增加 API 调用次数
5. 健康检查监控：部署 HTTP 服务时定期检查 /health 端点

系统要求

资料来源：README.md:1-10

安装方式

通过 npm 全局安装

npm install -g suggest-skills

通过 npx 直接运行

npx suggest-skills <command>

从源码构建

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

环境变量配置

必需配置

# JSON 数组格式
export SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]'

# 逗号分隔格式
export SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'

可选配置

GITHUB_PAT 用于对 api.github.com 的认证请求，可有效提高 API 速率限制。

export GITHUB_PAT="ghp_xxxxxxxxxxxx"

资料来源：README.md:1-20

运行模式

stdio 模式

stdio 模式适用于与本地 MCP 客户端直接集成，通过标准输入输出进行通信。

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

此模式适合集成到支持 MCP 协议的开发工具中。

HTTP 服务器模式

HTTP 模式提供网络 HTTP 接口，适合远程访问和分布式架构部署。

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

#### 服务端点

http://localhost:3100/mcp      # MCP 协议端点
http://localhost:3100/health  # 健康检查端点

资料来源：README.md:20-35

命令行接口

generate 命令

生成技能清单文档，从 GitHub 仓库扫描技能目录。

npx suggest-skills generate <github-url>

#### 参数说明

#### 基本用法

# 从 skills 目录生成清单
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

#### 输出文件

generate 命令会在当前工作目录生成以下文件：

#### 扫描规则

graph TD
    A[GitHub URL] --> B{--recursive 参数}
    B -->|否| C[扫描直接子目录]
    B -->|是| D[递归扫描所有子目录]
    C --> E[发现 SKILL.md 或 DESIGN.md]
    D --> E
    E --> F[收集同目录资源文件]
    F --> G[生成清单文件]

• GitHub blob URL 会自动转换为 raw.githubusercontent.com URL
• 符号链接会被下载但不递归遍历
• 空生成的输出会被跳过，不写入文件

资料来源：README.md:35-60

server 命令

启动 HTTP 服务器运行 MCP 端点。

npx suggest-skills server --port <number>

#### 参数说明

CLI 选项汇总

资料来源：README.md:15-25

MCP 工具接口

suggest_skills

推荐可用技能的工具。

返回内容：生成的指令负载，指导智能体如何获取技能、扫描本地安装、对比远程与本地能力。

fetch_manifest

获取清单文件内容。

返回内容：清单文件的原始文本内容。

download_skill

下载技能目录中的所有文件。

返回内容：文件夹中每个文件的路径、UTF-8 文本内容及符号链接信息。

graph LR
    A[MCP 客户端] -->|suggest_skills| B[返回推荐指令]
    A -->|fetch_manifest| C[获取清单]
    A -->|download_skill| D[下载技能文件]
    B --> E[用户选择技能]
    E --> D
    D --> F[本地文件]

Docker 部署（推荐架构）

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

ENV SUGGEST_SKILLS_MANIFEST_URLS="https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md"

EXPOSE 3100

CMD ["npx", "suggest-skills", "server", "--port", "3100"]

Docker Compose 编排

version: '3.8'

services:
  suggest-skills:
    image: suggest-skills:latest
    ports:
      - "3100:3100"
    environment:
      - SUGGEST_SKILLS_MANIFEST_URLS=https://example.com/manifest.md
      - GITHUB_PAT=${GITHUB_PAT}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3100/health"]
      interval: 30s
      timeout: 10s
      retries: 3

项目架构

graph TD
    subgraph 配置层
        A[环境变量] --> B[Config 模块]
        B --> C[配置验证]
    end
    
    subgraph 核心层
        D[MCP 服务器] --> E[工具注册]
        F[CLI 工具] --> G[GitHub 目录扫描]
        G --> H[清单生成器]
    end
    
    subgraph 传输层
        I[stdio 传输] 
        J[HTTP 传输]
    end
    
    B --> D
    B --> F
    E --> I
    E --> J
    H --> K[Markdown 输出]

核心模块

故障排查

常见问题

健康检查

部署后验证服务状态：

curl http://localhost:3100/health

正常响应返回 HTTP 200 状态码。

日志级别

通过环境变量启用调试日志：

DEBUG=suggest-skills:* npx suggest-skills server --port 3100

最佳实践

1. 始终设置 GitHub PAT：生产环境建议配置认证令牌以避免 API 限制
2. 使用版本化的清单 URL：避免清单更新导致行为不一致
3. 配置健康检查：容器编排中设置健康检查探针
4. 分离配置与部署：使用环境变量管理配置，便于不同环境切换
5. 限制网络暴露：stdio 模式优先用于敏感环境

资料来源：README.md:1-80

Pitfall Log / 踩坑日志

项目：sator-imaging/suggest-skills

摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.

3. 运行坑 · 来源证据：v1.0.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。

4. 运行坑 · 来源证据：v1.1.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。

5. 运行坑 · 来源证据：v1.2.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。

6. 运行坑 · 来源证据：v1.3.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。

7. 维护坑 · 来源证据：v1.0.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。

8. 维护坑 · 来源证据：v1.0.3

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。

9. 维护坑 · 来源证据：v2.0.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing

11. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium

12. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：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.

13. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium

14. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown

15. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown