仓库概览与架构

项目定位与核心能力

suggest-skills 是一个基于 Model Context Protocol 的服务器，专为推荐与分发仓库专属的 AI Agent 技能（skill）而设计。根据 package.json 的描述，项目的官方定位是 "MCP server that suggests repository-specific AI agent skills"，当前稳定版本为 2.0.6，许可证为 Apache-2.0。

项目通过单一可执行入口 dist/index.js（由 bun build 打包）提供三大核心能力：

• 生成技能清单：从 GitHub 仓库目录扫描 SKILL.md 与 DESIGN.md，输出 Markdown 表格形式的清单文件
• MCP 服务器：以 stdio 或 HTTP 模式运行，向 Agent 暴露 suggest_skills、download_skill、fetch_manifest 三个工具
• 技能下载：将 GitHub 上的技能文件夹完整下载到本地，默认输出到 .agents/skills

项目明确声明自身不提供安全检查能力，安全扫描由外部 NVIDIA SkillSpector 通过 CI 工作流执行，并写入清单的 Security Risk 列（v2.0.5 起在风险列中加入建议信息）。

资料来源：README.md:1-40 package.json:1-50

系统架构与模块划分

代码库采用"小而专"的模块化设计，将运行时关注点拆分到不同文件，主要技术栈为 TypeScript + Bun + @modelcontextprotocol/sdk + cac + ts-fibers。整体架构如下：

graph TB
  A[index.ts 入口] --> B[config.ts<br/>CLI 解析与运行时模式]
  B --> C{CliRuntimeMode}
  C -->|stdio| D[core.ts<br/>MCP 工具注册]
  C -->|server| E[StreamableHTTP<br/>传输层]
  C -->|generate| F[cmd_generate.ts<br/>清单生成]
  C -->|download| G[download.ts<br/>GitHub 下载与缓存]
  D --> H[utils.ts<br/>URL 规范化]
  D --> I[suggest.ts<br/>推荐逻辑与提示词]
  D --> J[constants.ts<br/>工具名称与描述]
  F --> K[generate.ts<br/>树分析与 URL 格式化]
  F --> G
  G --> H

各模块职责清晰：src/config.ts 负责 CLI 解析并定义可识别的 ConfigError；src/core.ts 负责 MCP 工具注册（共享同一份服务器创建逻辑）；src/cmd_generate.ts 负责 SKILL.md / DESIGN.md 的 front matter 解析与清单组装；src/download.ts 负责 GitHub 目录树下载、并发控制与清单缓存；src/utils.ts 与 src/generate.ts 提供 URL 规范化与树分析工具。ts-fibers 用于协作式并发，避免阻塞主事件循环。

资料来源：src/config.ts:1-40 src/cmd_generate.ts:1-50 src/download.ts:1-30 src/generate.ts:1-30

运行时模式与传输层

CLI 通过 src/config.ts 中的 parseCli 函数将用户输入归类为四种 CliRuntimeMode：

两种 MCP 传输模式（stdio 与 HTTP）共享同一份服务器创建逻辑，仅在外层传输包装上存在差异——这正是 README 中强调的"最小传输包装"原则。SUGGEST_SKILLS_MANIFEST_URLS 是 MCP 模式的必需环境变量，可接受 JSON 数组、逗号分隔或换行分隔字符串；GitHub blob 链接会被 normalizeGithubRawUrl 自动转换为 raw.githubusercontent.com 原始链接。GITHUB_PAT 可选，用于突破 api.github.com 的匿名速率限制。v2.0.0 起移除了已废弃的 --manifest-urls CLI 选项。

资料来源：src/config.ts:40-80 src/utils.ts:1-30 README.md:50-110

关键数据流与 MCP 工具

生成清单的数据流（以 generate 模式为例）：

1. parseCli 解析 URL 后调用 normalizeGithubRawUrl 规范化 GitHub 链接
2. cmd_generate.ts 借助 GitHub 递归树接口枚举目录，识别 SKILL.md 与 DESIGN.md 及其捆绑资源
3. 每个 Markdown 文件被解析 front matter（name、description），构建 GeneratedEntry；若 front matter 解析失败且文件为 DESIGN.md，则回退为仅 Markdown 视图
4. 三个清单文件（<owner>.<repo>[.<path>].skills.md、.designs.md、.agents.md）被写出，文件名自动去除冗余类型后缀；空文档被跳过，避免无意义的覆盖提示

MCP 工具三件套（src/constants.ts）：

• suggest_skills：为当前仓库推荐 AI Agent 技能（其推荐逻辑与提示词位于 src/suggest.ts）
• download_skill：下载 GitHub 技能文件夹并返回文件原文
• fetch_manifest：拉取清单原文，自 v1.3.0 起具备进程内缓存（MANIFEST_CACHE in src/download.ts），并发度限制为 DOWNLOAD_CONCURRENCY = 4

社区反馈显示 v2.0.1 修复了下载与生成命令在文件实际写入校验上的缺陷，v2.0.6 修复了空 DESIGN 清单条目被错误写入的问题——这两项修复都强化了数据流末端的健壮性。

资料来源：src/cmd_generate.ts:50-100 src/download.ts:30-60 src/constants.ts:1-7 src/suggest.ts:1-40

编码规范与扩展指引

README 明确指出项目的编码标准：模块小而专、显式配置验证（ConfigError）、MCP 工具使用类型化 schema 与结构化输出、传输层仅做最小封装、测试以"可观察行为"为中心。贡献者应优先更新 src/config.ts 等共享模块，再考虑添加传输特定行为，并以 SPEC.md 作为预期行为的起点。

参见

• CLI 与配置参考
• MCP 工具接口详解
• 生成清单数据流
• 安全扫描与 SkillSpector 集成

MCP 工具与服务器传输层

概述与设计目标

suggest-skills 是一个基于 Model Context Protocol（MCP）协议的服务器，其核心职责是向 AI 代理推荐与当前仓库上下文相匹配的技能（SKILL.md / DESIGN.md / Agent 描述文件），并提供下载与清单抓取能力。整个系统围绕 createServer 工厂构建，运行时支持两种传输方式：stdio 与流式 HTTP，二者共享同一份核心业务逻辑 资料来源：src/core.ts:7-9。

项目的依赖在 package.json 中明确声明：@modelcontextprotocol/sdk 用于协议实现，cac 用于 CLI 解析，ts-fibers 用于并发控制（用于 GitHub 目录树与清单并发抓取），zod 用于工具入参的运行时校验。运行时要求 bun >= 1.3.13，打包产物为 dist/index.js，通过 npx suggest-skills 调用 资料来源：package.json:6-44。

MCP 工具注册结构

服务器通过 McpServer 实例注册三件套工具，对应不同的工作流阶段 资料来源：src/core.ts:10-78：

三个工具均使用 zod 定义 inputSchema，其中 download_skill 与 fetch_manifest 还额外声明了 outputSchema（files 数组与 content 字符串），使 MCP 客户端可以同时获得 text 内容与 structuredContent 强类型结果 资料来源：src/core.ts:54-78。

SUGGEST_TOOL_NAME 的处理流程为：先调用 normalizeGithubRawUrl 把传入的 manifestUrl 从 github.com/.../blob/... 形式转换为 raw.githubusercontent.com 直链，然后交给 buildSuggestionResponse 构造推荐结果 资料来源：src/core.ts:11-30。该响应文本由 src/suggest.ts 中的 buildSuggestionResponse 产出，其中包含「仓库模式识别 → 本地技能扫描 → 远程技能对比 → 建议表格」等步骤 资料来源：src/suggest.ts:1-50。

DOWNLOAD_TOOL_NAME 接收 url 后调用 downloadGithubFolder，后者通过 parseGithubDirectoryUrl 解析 owner/repo/ref/path，再递归拉取 GitHub 目录树并以 Fibers 限制 DOWNLOAD_CONCURRENCY = 4 的并发度 资料来源：src/download.ts:21-89。

FETCH_MANIFEST_TOOL_NAME 走 fetchManifestText，自 v1.3.0 起加入了进程内 Map 缓存 MANIFEST_CACHE，对同一 URL 命中后直接返回，避免重复网络往返 资料来源：src/download.ts:25-35。

传输层与 CLI 路由

src/config.ts 定义了四种运行时模式（CliRuntimeMode），通过 cac 派发到不同的处理函数 资料来源：src/config.ts:18-22：

flowchart LR
    A[npx suggest-skills] --> B{cac 解析}
    B -->|generate <url>| C[onGenerate]
    B -->|download <url>| D[onDownload]
    B -->|server --port| E[onServer]
    B -->|默认 / stdio| F[onStdio]
    C --> G[createServer 不启动]
    D --> G
    E --> H[HTTP transport]
    F --> I[stdio transport]

• stdio 模式：无任何子命令时触发，使用 @modelcontextprotocol/sdk 的 StdioServerTransport，适合被 Cursor、Claude Desktop 等宿主通过 mcpServers 配置拉起 资料来源：src/config.ts:55-67, README.md:1-60。
• server 模式：通过 --port <port> 指定端口，启动流式 HTTP 传输，监听 http://localhost:<port>/mcp 路径，并附带健康检查 资料来源：README.md:1-50。
• generate 与 download 模式不会真正启动 MCP 服务器，而是直接执行清单生成或目录下载并写入当前工作目录 资料来源：src/config.ts:38-54。

全局 -o, --output <dir> 选项用于覆盖默认输出目录 DEFAULT_OUTPUT_DIRECTORY = ".agents/skills" 资料来源：src/config.ts:24, src/config.ts:36。

配置、并发与常见失败模式

环境变量 SUGGEST_SKILLS_MANIFEST_URLS 是 stdio 与 HTTP 模式必需的清单源，兼容 JSON 数组、逗号分隔、换行分隔三种写法；GITHUB_PAT 可选，用于提高 api.github.com 的速率限制 资料来源：README.md:1-50。SUGGEST_SKILLS_MANIFEST_URLS 解析失败时会抛出 ConfigError，由 config.ts 中显式的校验逻辑捕获 资料来源：src/config.ts:26-30。

GitHub 链接规范化集中在 src/utils.ts 的 normalizeGithubRawUrl 中：仅接受 github.com 域名下 blob 或 raw 路径，并将 repo.git 形式归一化 资料来源：src/utils.ts:14-35。parseGithubDirectoryUrl 则负责将目录 URL 拆解为 owner/repo/ref/path 元组供 downloadGithubFolder 使用 资料来源：src/utils.ts:39-60。

常见失败模式与社区反馈一致：

• 空 DESIGN 条目：v2.0.6 修复了空 DESIGN.md 清单条目被错误生成的问题，由 PR #238 贡献 资料来源：release v2.0.6。
• 下载写入校验缺失：v2.0.1 强化了 download 与 generate 命令的「实际写入文件」校验（PR #119），避免在无写权限或路径被占用时返回假成功 资料来源：release v2.0.1。
• --manifest-urls 弃用：v2.0.0 删除了已弃用的 CLI 选项，统一通过环境变量与服务器配置传递 资料来源：release v2.0.0。
• 清单抓取频繁重发：v1.3.0 引入 fetch_manifest 的进程内缓存以缓解该问题 资料来源：release v1.3.0。

参见

• 项目主页与快速开始
• 官方技能清单
• 社区技能清单
• SPEC.md（项目规范起点）
• SkillSpector 安全扫描工作流

CLI 命令与清单生成

概览与设计目标

suggest-skills 是一个面向 AI Agent 的 MCP（Model Context Protocol）服务器，其 CLI 入口同时承担两类职责：（1）在本地为 MCP 客户端（如 Claude Desktop）注册技能推荐工具；（2）从 GitHub 仓库离线生成技能清单（manifest）markdown 文件，供后续由 MCP 服务器读取。CLI 与清单生成模块位于同一进程入口，通过 cac 命令行框架分流到不同的运行时模式。

资料来源：src/config.ts:1-12，package.json:1-14

整个项目以 Bun 为运行时构建产物，命令入口 dist/index.js 由 src/index.ts 编译生成，构建脚本通过 bun build --target node --production 打包。资料来源：package.json:13-19

flowchart LR
    A["命令行参数"] --> B["cac 解析"]
    B --> C1{"子命令"}
    C1 -->|generate| D["cmd_generate"]
    C1 -->|download| E["download.ts"]
    C1 -->|server| F["HTTP 传输"]
    C1 -->|默认| G["stdio 传输"]
    D --> H["GitHub 目录树"]
    H --> I["markdown 清单文件"]
    E --> J["GitHub API/RAW"]
    J --> K["本地技能目录"]
    I --> G
    K --> G

CLI 命令解析

src/config.ts 中通过 registerCommands 注册全部子命令，运行时模式由联合类型 CliRuntimeMode 表达，覆盖 stdio、generate、download、server 四种 kind。命令解析由 cac("suggest-skills") 完成，版本号取自 package.json。资料来源：src/config.ts:30-50

可用的子命令与全局选项如下表所示：

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

parseCli 函数接收 process.argv 和 process.env，把 SUGGEST_SKILLS_MANIFEST_URLS 等环境变量合并进 SuggestSkillsConfig.outputDirectory 与 sourceUrls 字段，再交给后续的 MCP 注册逻辑。GitHub blob 链接会被 normalizeGithubRawUrl 自动转换为 raw.githubusercontent.com 形式。资料来源：src/config.ts:60-85，src/utils.ts:18-38

清单生成流程

src/cmd_generate.ts 是清单生成的核心实现。generateSkillsManifest 与 generateOutputs 接收一个 GitHub URL 与可选的 GenerateOptions，最终产出 GeneratedOutputs，包含 skills、designs、agents 三类 markdown 文档。文件命名基于 generate 根路径，例如 <owner>.<repo>[.<path>].skills.md，并会规范化去除冗余类型后缀（如 some-skills.md 而非 some-skills.skills.skills.md）。资料来源：src/cmd_generate.ts:60-100

生成规则按文档类别使用 GENERATED_MARKDOWN_OPTIONS 配置：

• skills（SKILL.md）：包含 Bundled Assets 列，资产以纯文本列出；
• designs（DESIGN.md）：资产以可点击链接形式呈现，缺失描述时输出 None；
• agents（顶层带 front matter 的 markdown）：仅 Name 与 Description 两列。

资料来源：src/cmd_generate.ts:45-58，README.md:120-150

isEmptyGeneratedDocument 通过比对表头判断输出是否为空，空文档会被跳过且不会触发覆盖提示，这是 v2.0.6 修复后对 DESIGN.md 空清单的统一行为。资料来源：src/cmd_generate.ts:25-30，release notes v2.0.6

SKILL.md 与 DESIGN.md 的发现规则如下：

• 默认（不带 --recursive）：仅扫描 generate 根的直系子目录；
• 带 --recursive：扩展为递归扫描，但 .agents.md 的发现逻辑不受该选项影响；
• 符号链接不会被遍历，但可能作为静态资产出现在清单中；
• DESIGN.md 会从 YAML front matter 读取可选的 name 与 description，缺少 description 时输出 None。

资料来源：src/cmd_generate.ts:100-150，README.md:135-160

GitHub 资源获取与缓存

src/download.ts 封装了所有与 GitHub 通信的逻辑。fetchManifestText 实现了一个进程内 Map 缓存（MANIFEST_CACHE），同一 URL 在一次 MCP 会话中只下载一次；clearManifestCache 暴露给测试使用。该缓存是从 v1.3.0 起新增的，目的是减少对 fetch_manifest 工具的重复网络请求。资料来源：src/download.ts:30-50，release notes v1.3.0

downloadGithubFolder 通过 resolveGithubFolderUrl 解析 tree 链接并调用 GitHub Contents API 获取目录树，再并发下载每个文件；并发度由常量 DOWNLOAD_CONCURRENCY = 4 控制。v2.0.1 修复了在没有正确权限或网络中断时命令声称完成但实际未写入文件的问题，改为对真实写入进行校验。资料来源：src/download.ts:55-85，release notes v2.0.1

src/utils.ts 提供 URL 解析工具：normalizeGithubRawUrl 把 github.com/.../blob/<ref>/<path> 转换为 raw.githubusercontent.com/.../<ref>/<path>；parseGithubDirectoryUrl 则把 GitHub 目录链接解析为 { owner, repo, ref, path } 形式的 GithubDirectoryLocation。如果 URL 不是这两种形式之一，函数返回 undefined 以便调用方走回退分支。资料来源：src/utils.ts:18-60

运行时与 MCP 工具集成

CLI 解析得到的 CliRuntimeMode 在 src/index.ts 中被消费，根据 kind 分别启动 stdio 传输、HTTP 传输，或直接执行 cmd_generate / download 后退出。MCP 工具名在 src/constants.ts 中集中定义：suggest_skills、download_skill、fetch_manifest。src/suggest.ts 负责拼装返回给客户端的提示词模板 INSTRUCTIONS，并通过占位符 ###manifests### 与 ###outdir### 注入运行时配置。资料来源：src/constants.ts:1-10，src/suggest.ts:10-50

需要注意的是：

• v2.0.0 移除了已废弃的 --manifest-urls CLI 选项，manifest URL 必须通过 SUGGEST_SKILLS_MANIFEST_URLS 环境变量提供；
• GITHUB_PAT 可选，用于提高 api.github.com 的速率上限；
• SkillSpector 安全扫描由 generate-manifests.yml 工作流在 CI 中运行，结果回写到清单的 Security Risk 列。

资料来源：src/config.ts:80-95，README.md:160-180，[release notes v2.0.0]

参见

• README.md
• package.json
• Release Notes

概览与定位

suggest-skills 本身是一个 Model Context Protocol（MCP）服务器，主要用于推荐和下载仓库相关的 AI Agent 技能。安全扫描能力并非由 MCP 服务器在运行时执行，而是通过外部集成的 NVIDIA SkillSpector 在 CI 阶段完成。每个技能会被独立扫描，最终的风险评分被写入预构建清单的 Security Risk 列。

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

需要注意的核心边界：

• suggest-skills 在 stdio / HTTP 模式下不提供安全检查（This tool doesn't provide security checks）。
• 真实的安全评估应通过 skills.sh/official 进行。
• 风险分数仅作为 manifest 的辅助信息，帮助使用者快速识别可疑技能。

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

CI 集成工作流

安全扫描通过 generate-manifests.yml 工作流触发，并与 manifest 生成串联执行。其大致流程如下：

graph LR
    A[GitHub Actions 触发] --> B[checkout 仓库]
    B --> C[setup Bun 运行时]
    C --> D["npx suggest-skills generate"]
    D --> E[生成 skills/agents/designs manifest]
    E --> F[调用 NVIDIA SkillSpector 扫描]
    F --> G["写入 Security Risk 列"]
    G --> H[bot 提交 manifest 回仓库]

资料来源：README.md:1-100, package.json:24-38

工作流执行期间生成的 manifest 会被提交回仓库的 official/ 与 community/ 目录，供 MCP 客户端后续通过 fetch_manifest 工具读取。

资料来源：src/core.ts:1-100, src/download.ts:1-80

风险分级与统计

从 v2.0.5 开始，扫描结果按照严重度被拆分为两个互斥的统计桶：

风险评分与"是否建议安装"的结论一起以 Security Risk 列呈现，markdown 统计输出以项目列表（bullet list）形式汇总。

资料来源：release notes v2.0.5, release notes v2.0.3

CLI 配置与执行控制

SkillSpector 相关的行为通过 CI 阶段的命令参数控制，主要包括：

• --target <glob>：自 v2.0.3 起支持 glob 模式，仅扫描匹配的技能子集，加快增量扫描。
• timeout 与 concurrency：自 v2.0.2 起用于限制单次扫描耗时与并发数，避免长任务阻塞 CI。

这些参数由工作流直接拼装到 SkillSpector 调用中，不通过 suggest-skills 的 CLI 暴露。suggest-skills 自身的 CLI 仅控制 manifest 生成路径、输出目录（默认 .agents/skills）与服务器端口。

资料来源：src/config.ts:1-100, release notes v2.0.2, release notes v2.0.3

限制与最佳实践

• 运行时不扫描：MCP 客户端调用 suggest_skills 或 download_skill 时不会触发 SkillSpector，扫描仅在 CI 中发生。
• 静态分析为主：扫描针对 SKILL.md 与捆绑资源进行，不修改文件内容，也不替代人工审查。
• 缓存依赖 fetch_manifest：MCP 工具 fetch_manifest 自 v1.3.0 起使用进程内缓存，重复读取同一 manifest URL 不会再走网络，但缓存不会自动失效。

资料来源：src/download.ts:1-80, release notes v1.3.0

最佳实践建议：

• 在自动化流水线中始终使用带有 Security Risk 列的官方 manifest。
• 对于 Dangerous 等级的技能，应在 PR 评审中显式确认后再纳入。
• 升级 manifest 后留意 CI 输出，因为扫描规则与阈值会随 SkillSpector 版本演进。

See Also

• README.md
• MCP 服务器与工具注册：src/core.ts
• CLI 行为与运行时模式：src/config.ts
• GitHub 内容抓取与缓存：src/download.ts
• manifest 生成：src/cmd_generate.ts
• 官方技能清单：./official/
• 社区技能清单：./community/

Pitfall Log / 踩坑日志

项目：sator-imaging/suggest-skills

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | 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 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/sator-imaging/suggest-skills | release_recency=unknown