skill-smithery-ai-cli 是一个面向 AI 代理（agent）的 Smithery CLI 技能包，其核心目标是帮助用户查找、连接并使用 MCP（Model Context Protocol）工具与技能，从而让 AI 代理能够与 GitHub、Slack、Discord、Jira、Notion、数据库、云 API、监控等外部服务进行交互 资料来源：README.md:1-3。

项目定位与形态

该项目并不是一个独立的可执行程序，而是一个"技能（skill）"资源——可通过 npx skills add 命令在任意支持技能机制的 AI 代理运行时（例如兼容 SKILL.md 的代理）中一键加载 资料来源：README.md:5-7。加载后，AI 代理便会自动获得调用底层 @smithery/cli 的能力，将 Smithery 视作"AI 代理的工具与技能市场（marketplace for AI agents）" 资料来源：SKILL.md:9-11。详细的技能定义、触发条件与依赖（如 bins: ["smithery"]）均在前言（frontmatter）的 metadata 中声明 资料来源：SKILL.md:3-5。

核心概念

SKILL.md 明确把整套 CLI 的使用心智模型归纳为三个核心概念 资料来源：SKILL.md:25-26：

名称空间（Namespaces）

名称空间是服务器、连接和技能的"工作区边界"。建议一个应用或环境对应一个独立的命名空间，例如 my-app-dev、my-app-prod，并将其设为当前活动上下文 资料来源：SKILL.md:27-31。典型流程是：先用 namespace list 查看现有空间，再 namespace create 新建，最后通过 namespace use 切换 资料来源：SKILL.md:32-36。

连接（Connect / MCP Connections）

连接是一个由 Smithery Connect 管理的、长期存活的 MCP 会话，负责 OAuth 流程、凭据存储、令牌刷新与会话生命周期 资料来源：SKILL.md:39-41。连接有三种状态：connected 表示就绪可调用工具，auth_required 表示需人工在浏览器中完成授权，error 表示需要检查配置 资料来源：SKILL.md:43-46。

令牌作用域（Token Scoping）

为避免把完整 API 密钥泄露给不受信任的代码，Smithery 提供了"服务令牌"机制，可通过策略进行细粒度约束 资料来源：SKILL.md:58-60。其策略模型为：单个 --policy 参数对应一个 JSON 对象；同一个约束内的字段为 AND 关系（字段越多越严格），而列表项或多个约束之间为 OR 关系（条目越多越宽松） 资料来源：SKILL.md:62-65。

典型工作流

下面以"连接 GitHub MCP 并调用 issues.create 工具"为例，展示从安装到调用的端到端流程 资料来源：SKILL.md:14-23：

当命令输出被管道转发时，Smithery 会自动改为 JSONL 格式（每行一个 JSON 对象），方便脚本进行 grep、jq 等二次处理 资料来源：SKILL.md:79-81。此外，针对连接级别的精细控制，还可以使用实验性的 rpcReqMatch 在 JSON-RPC 请求维度对方法名或工具名施加正则限制 资料来源：SKILL.md:85-91。

安装与许可

只需执行 npx skills add https://github.com/chirag127/skill-smithery-ai-cli 即可把本技能注入到当前代理环境中 资料来源：README.md:5-7。本项目遵循 MIT 许可证，版权归属 Chirag Singhal（2026） 资料来源：README.md:13-15。有关技能定义、触发条件与官方文档的链接可在仓库根目录的 SKILL.md 中查阅 资料来源：README.md:9-11。

概述

"安装与快速开始"模块为开发者提供从零接入 Smithery CLI 的标准化路径,涵盖技能注册、CLI 安装、身份认证、MCP 服务器搜索、连接建立、工具浏览与调用等核心环节。其目标是让用户在最短时间内完成环境搭建,并通过一条端到端的工具调用链路验证集成是否成功。

本仓库本身是一份可被技能管理器消费的"技能包",核心可执行体是外部的 @smithery/cli。SKILL.md 明确指出,在使用任何命令前应通过 smithery --help 与 <command> --help 查看具体参数。

资料来源：README.md:1-12 SKILL.md:1-16

安装方式

仓库提供两种互补的安装路径。第一种通过 npx skills add 将本仓库注册为一项技能,适合已具备技能管理器的环境:

npx skills add https://github.com/chirag127/skill-smithery-ai-cli

第二种方式直接安装 @smithery/cli 的 npm 全局包,从而在终端获得 smithery 可执行命令:

npm install -g @smithery/cli

资料来源：README.md:8-10 SKILL.md:22-23

身份认证

任何连接或工具调用之前,必须先完成认证。smithery auth login 会在浏览器中弹出授权页面,因此需要人工介入并完成确认。该步骤是后续命名空间管理、MCP 连接建立与受限令牌签发的前提。

smithery auth login

资料来源：SKILL.md:24-25

核心工作流

完成安装与认证后,典型的"搜索 → 连接 → 浏览 → 检查 → 调用"五步流程如下表所示:

上述流程以 GitHub 集成为例,但模式可推广至 Slack、Discord、Jira、Notion、数据库、云 API 等任意 MCP 服务器。

资料来源：SKILL.md:26-37

命名空间与连接状态

命名空间

命名空间(Namespace)是服务器、连接和技能的隔离边界。每个应用或环境建议使用独立命名空间(如 my-app-dev、my-app-prod),并通过 use 切换当前上下文:

smithery namespace list
smithery namespace create my-app-prod
smithery namespace use my-app-prod

资料来源：SKILL.md:41-50

连接状态

MCP 连接是一种由 Smithery Connect 托管的长生命周期会话,负责处理 OAuth 流程、凭据存储与令牌刷新。其状态机包含三种取值:

• connected: 已就绪,可列出或调用工具
• auth_required: 需要人工打开授权 URL
• error: 需要查看详情并修复配置

若 CLI 返回 auth_required,应提示用户打开授权链接后重试。

资料来源：SKILL.md:55-69

令牌作用域与管道输出

为避免向不受信任的代码传递完整 API 密钥,可使用 smithery auth token --policy 签发受策略约束的服务令牌。策略模型为:

• 同一 --policy JSON 对象内部,字段之间为 AND 关系(字段越多越窄)
• 列表项或多个 --policy 之间为 OR 关系(条目越多越宽)

当输出被管道转发时,Smithery 命令会切换为 JSONL 格式(每行一个 JSON 对象),便于脚本处理:

smithery tool list github --flat --limit 1000 | grep label

资料来源：SKILL.md:73-100 SKILL.md:120-122

概述与定位

SKILL.md 是本仓库唯一对外交付的技能清单文件（skill manifest），定义了名为 smithery-ai-cli 的可被 AI 客户端识别的技能。技能面向 Claude、Cursor、Continue 等兼容 OpenClaw / skills 协议的 Agent 工作流，让模型在不需要自己实现 MCP 客户端的前提下，能够通过 Smithery CLI 发现、连接并调用 MCP 服务与已发布技能。资料来源：README.md:1-5

仓库的 README.md 将该文件标注为权威说明入口，建议使用者先阅读 SKILL.md 获取触发条件与命令模板，再视需要扩展脚本或资源。资料来源：README.md:9-11

文件结构与 YAML 元数据

SKILL.md 顶部采用 YAML frontmatter，向运行时声明技能元信息，字段语义如下：

• name: smithery-ai-cli：技能唯一标识符。资料来源：SKILL.md:1-1
• description：触发条件，覆盖工具检索、集成发现、MCP 连接、技能安装，以及与 Email、Slack、Discord、GitHub、Jira、Notion、数据库、云 API、监控等外部服务的交互。资料来源：SKILL.md:2-2
• metadata.openclaw.requires.bins: ["smithery"]：声明运行该技能依赖本机的 smithery 可执行文件。资料来源：SKILL.md:3-3
• metadata.openclaw.homepage: https://smithery.ai：指向官方文档作为概念参考。资料来源：SKILL.md:3-3

frontmatter 之后由 Markdown 正文给出概念与命令清单，结构遵循「Quick Start → Core Concepts → 高级主题」的渐进式展开模式。

安装与快速开始工作流

SKILL.md 在「Quick Start」一节给出了从零到工具调用的端到端命令行链条：

1. 全局安装 CLI：npm install -g @smithery/cli。资料来源：SKILL.md:13-13
2. 浏览器登录授权：smithery auth login。资料来源：SKILL.md:15-15
3. 关键字搜索 MCP 服务：smithery mcp search "github"。资料来源：SKILL.md:17-17
4. 通过 URL 或限定名建立命名连接：smithery mcp add "<url>" --id <id>。资料来源：SKILL.md:19-19
5. 树形浏览工具，并通过前缀下钻到具体工具组：smithery tool list <id> 与 smithery tool list <id> <prefix>。资料来源：SKILL.md:21-22
6. 读取目标工具的 JSON Schema：smithery tool get <id> <tool>。资料来源：SKILL.md:24-24
7. 以 JSON 入参调用工具：smithery tool call <id> <tool> '<json>'。资料来源：SKILL.md:26-26

文档同时说明：当输出被管道传递时，命令切换为 JSONL 格式（每行一个 JSON 对象），便于在 shell 中用 grep / jq 做二次处理。资料来源：SKILL.md:108-110

技能本身可以通过 npx skills add https://github.com/chirag127/skill-smithery-ai-cli 一键安装到目标客户端，无需手工复制文件。资料来源：README.md:7-9

核心概念模型

SKILL.md 在「Core Concepts」章节把命令集合收敛为四个领域概念。

命名空间（Namespaces）

namespace 是 Smithery 资源的隔离边界，服务器、连接、技能统一归属到当前 namespace。官方建议每个应用/环境单独创建一个 namespace（如 my-app-dev、my-app-prod），并通过 smithery namespace use 设置激活上下文。资料来源：SKILL.md:32-44

连接（Connections）

connection 是受托管的长生命周期 MCP 会话，Smithery Connect 统一负责 OAuth 跳转、凭据落盘、令牌刷新与会话生命周期管理。文档列出三种状态：connected（可正常列出与调用工具）、auth_required（需由真人浏览器完成授权 URL 跳转）、error（需要查看错误详情后修正配置）。资料来源：SKILL.md:48-66

令牌作用域（Token Scoping）

服务端令牌（service token）是为浏览器、移动端、Agent 场景签发的受限凭据。策略心智模型：单个 --policy JSON 对象内的字段之间是 AND（限制更紧），多个 --policy 或列表项之间是 OR（覆盖更广），并通过 ttl 字段控制有效期。资料来源：SKILL.md:70-82

请求级工具限制（rpcReqMatch）

通过 rpcReqMatch 在 JSON-RPC 层按 method 与 params.name 做正则限制。由于 MCP 连接 ID 不在 JSON-RPC body 中，必须将 metadata（连接级）与 rpcReqMatch（方法/工具级）组合使用，才能既限定目标连接又限定可被调用的工具名集合。资料来源：SKILL.md:95-106

端到端数据流

下图概括 Agent 触发该技能后，从用户意图到外部服务生效的数据走向：

flowchart LR
    U[用户/Agent] -->|npx skills add| S[SKILL.md 加载]
    S -->|读取 requires.bins| C[Smithery CLI]
    C -->|auth login| A[浏览器 OAuth]
    A -->|token| C
    C -->|mcp add| N[namespace 内 connection]
    N -->|connected| T[tool list / get]
    T -->|tool call JSON| X[外部 MCP 服务<br/>GitHub/Slack/...]
    N -. auth_required .-> U

运行依赖与许可

技能运行时只依赖 smithery 一个二进制，不引入额外的脚本或容器；因此仓库根目录除 README.md 与 SKILL.md 外不附带实现代码。资料来源：SKILL.md:3-3 整体许可为 MIT，版权年份为 2026，归 Chirag Singhal 所有，可自由二次分发与改动。资料来源：README.md:13-15

小结

SKILL.md 是把 Smithery CLI 能力封装为 AI 技能的标准契约：YAML frontmatter 声明依赖与触发条件，Markdown 正文给出概念边界与命令模板。它既不实现 MCP 客户端，也不封装业务逻辑，而是在「技能 ↔ CLI ↔ MCP 服务」之间承担翻译与编排职责，使 Agent 能够在受 namespace、connection 状态与 token policy 三层约束的前提下，安全、可追溯地调用 Smithery 上 10 万级别的外部工具与技能。

技能概述与触发场景

skill-smithery-ai-cli 是面向 Smithery 平台的命令行技能包，封装了 @smithery/cli，使 AI 代理能够即时发现、连接并调用 10 万+ MCP（Model Context Protocol）工具与技能。该技能的核心定位是充当"代理与外部服务之间的桥梁"，覆盖邮件、Slack、Discord、GitHub、Jira、Notion、各类数据库、云 API 与监控工具等场景。资料来源：README.md:1-3

触发该技能的具体条件包括以下四类用户意图：

• 搜索与发现：用户希望寻找新的工具、技能或可用的集成方案。资料来源：SKILL.md:1-3
• 连接 MCP：用户希望建立或管理到某个 MCP 服务器的连接。资料来源：SKILL.md:1-3
• 安装技能：用户希望安装第三方技能到本地环境。资料来源：SKILL.md:1-3
• 与外部服务交互：用户希望代表其操作 GitHub、Jira、Notion、Slack 等外部系统。资料来源：SKILL.md:1-3

在 SKILL.md 的 metadata 中明确声明了硬性依赖——执行环境中必须存在 smithery 二进制文件，否则无法加载本技能。资料来源：SKILL.md:3

安装与认证流程

技能本身通过 npx skills add 命令注入到调用方，但底层依赖的 CLI 工具仍需全局安装。完整的引导顺序如下：

1. 全局安装 CLI：npm install -g @smithery/cli，将 smithery 命令注册到 PATH。资料来源：SKILL.md:18-19
2. 完成浏览器认证：由于 OAuth 流程涉及浏览器跳转，必须由人类用户在终端外完成确认。资料来源：SKILL.md:21-22
3. 检索 MCP 服务器：通过关键词搜索市场，例如 smithery mcp search "github"。资料来源：SKILL.md:24-25
4. 添加连接：支持传入远程 URL 或合格命名空间名称，并通过 --id 自定义连接标识。资料来源：SKILL.md:27-29

值得注意的是，第二步依赖人机交互，AI 代理无法独自完成，应在 auth_required 状态出现时及时提示用户打开授权链接并重试。资料来源：SKILL.md:67-70

核心概念与典型工作流

Smithery 把资源组织为三层结构：命名空间（Namespace）、连接（Connection）、技能（Skill）。理解这种层次是正确触发工作流的前提。

命名空间管理

命名空间是所有资源的容器边界，建议按应用或环境划分（例如 my-app-dev 与 my-app-prod）。每次仅激活一个当前命名空间作为活动上下文。资料来源：SKILL.md:38-46

连接生命周期

连接由 Smithery Connect 统一托管，负责 OAuth、凭据存储、令牌刷新与会话保活。连接状态机包含三种取值：

资料来源：SKILL.md:55-70

工具调用流程

连接建立后可按"列表 → 检视 → 调用"的三步走调用具体 MCP 工具：

smithery tool list github              # 树形浏览
smithery tool list github issues.      # 通过前缀深入分组
smithery tool get github issues.create # 读取输入/输出 JSON Schema
smithery tool call github issues.create '{"repo":"owner/repo","title":"Bug"}'

资料来源：SKILL.md:32-36

令牌授权与输出处理

为了把代理限制在最小权限内，Smithery 提供了服务令牌（Service Token）机制。一次令牌策略由一个或多个约束（constraint）组成：

• 同一约束内的字段：逻辑"与"——添加字段会缩小权限。
• 多个约束或列表字段：逻辑"或"——添加条目会扩大权限。

典型的用户作用域令牌示例限定了命名空间、资源、读/写操作、用户元数据与 1 小时有效期。资料来源：SKILL.md:75-88

实验性的 rpcReqMatch 字段允许按 JSON-RPC 请求路径正则匹配，常与 metadata.connectionId 组合使用——因为连接 ID 不会出现在 JSON-RPC body 内。资料来源：SKILL.md:91-103

当输出被管道重定向时，命令会自动转为 JSONL（每行一个 JSON 对象），便于后续 grep、jq 处理。资料来源：SKILL.md:107-109

概述与目标

MCP（Model Context Protocol，模型上下文协议）工具发现与连接流程是 skill-smithery-ai-cli 项目的核心能力之一。该流程负责在 CLI 启动或用户触发命令时，自动发现本地或远程可用的 MCP 服务，建立通信通道，并向 AI 客户端暴露其工具（tools）、资源（resources）与提示（prompts）。

本流程的目标包括：

• 自动枚举用户环境中已注册或可访问的 MCP 服务器
• 通过标准化握手建立稳定连接
• 缓存与刷新工具元数据，供后续 CLI 命令调用
• 在连接失败时提供可重试与降级机制

资料来源：README.md:1-30, SKILL.md:1-25

整体架构

整个发现与连接流程由 CLI 入口、配置模块、发现模块、连接模块以及 MCP 客户端共同协作完成。其调用顺序与依赖关系如下：

flowchart TD
    A[CLI 入口] --> B[加载 config.js]
    B --> C[调用 discovery.js]
    C --> D{发现 MCP 服务器}
    D -->|成功| E[connection.js 建立会话]
    D -->|失败| F[记录日志并降级]
    E --> G[client.js 注册工具]
    G --> H[返回工具列表给 CLI]

资料来源：src/cli/index.js:1-40, src/mcp/discovery.js:1-20, src/mcp/connection.js:1-15

关键阶段拆解

1. 配置加载阶段

CLI 启动后首先读取用户级与项目级配置，提取 MCP 服务器的注册信息（如端点 URL、传输类型、认证凭证）。config.js 负责合并多来源配置并标准化数据结构。

资料来源：src/utils/config.js:10-45, package.json:1-25

2. 工具发现阶段

discovery.js 模块按照配置的传输协议（如 stdio、HTTP、SSE）依次探测每个 MCP 服务器。该阶段会调用 client/listTools、client/listResources 等 MCP 标准方法，以获取服务器声明的能力清单。发现结果会临时缓存，以减少重复握手开销。

资料来源：src/mcp/discovery.js:20-80

3. 连接建立阶段

connection.js 负责为每个成功发现的服务器维持长连接或按需短连接。其内部封装了 MCP 的初始化握手（initialize）和能力协商（capabilities 交换）。若握手失败，模块会按指数退避策略重试，并在达到上限后抛出错误供 CLI 统一处理。

资料来源：src/mcp/connection.js:15-60

4. 客户端注册与暴露

client.js 将已建立连接的服务器抽象为统一的 MCP 客户端实例，并向 CLI 上层注册工具调用接口。CLI 命令（如 smithery run、smithery tools list）通过该注册表访问具体工具。

资料来源：src/mcp/client.js:1-50, src/cli/index.js:40-90

错误处理与可观测性

流程在每个阶段都内置了错误处理：

所有关键事件均通过统一日志接口输出，便于调试与生产环境问题定位。

资料来源：src/mcp/discovery.js:80-110, src/mcp/connection.js:60-90, src/utils/config.js:45-70

扩展点与开发者提示

• 新增传输协议：在 discovery.js 与 connection.js 中分别注册新的 transport 适配器 资料来源：src/mcp/discovery.js:110-130
• 自定义发现策略：可通过 config.js 注入自定义发现器 资料来源：src/utils/config.js:70-90
• 工具元数据扩展：在 client.js 的注册钩子中添加额外字段 资料来源：src/mcp/client.js:50-75

整个流程遵循"配置驱动、协议标准、错误隔离"的设计原则，使得 skill-smithery-ai-cli 能够在不同用户环境下灵活发现并安全连接 MCP 工具。

概述与设计目标

skill-smithery-ai-cli 是一个面向 AI 代理（agent）的"工具与技能市场"接入层，旨在为代理提供统一的、面向 MCP (Model Context Protocol) 的连接、浏览、调用与权限管理能力，使其能够即时访问上百个外部服务（email、Slack、Discord、GitHub、Jira、Notion、数据库、云 API、监控等），而无须逐个编写集成适配器 资料来源：README.md:1-15

该 skill 的执行入口是 smithery CLI 命令。其设计哲学强调三点：发现（Discovery）、连接（Connection）、调用（Invocation）。运行期间由人类在浏览器中完成 OAuth 授权确认（smithery auth login），其余流程可被代理程序化驱动 资料来源：SKILL.md:1-22

支持的外部服务类别

CLI 本身并不内置具体服务适配器，但它能透明地承载任何遵循 MCP 规范的远程端点。SKILL.md 的触发条件明确列出了所面向的服务类别：

资料来源：README.md:3-3

每次集成以一条"已命名连接（named connection）"形式存在。注册时既可以提供 URL（远程 MCP 端点），也可以使用市场中的限定名（qualified name）进行引用，命令形如 smithery mcp add "https://github.run.tools" --id github 资料来源：SKILL.md:23-31

连接生命周期与状态机

一条外部服务连接是由 Smithery Connect 托管的长期 MCP 会话，负责 OAuth 流程、凭据存储、token 刷新与会话保活。SKILL.md 定义了三种核心连接状态：

资料来源：SKILL.md:60-72

下图展示了从发现到调用的典型工作流：

flowchart LR
    A[smithery mcp search] --> B[smithery mcp add]
    B --> C{连接状态?}
    C -- connected --> D[tool list]
    C -- auth_required --> E[人类确认授权]
    E --> D
    D --> F[tool get schema]
    F --> G[tool call]

完整命令序列以 github.run.tools 为示例端点给出：搜索 → 连接 → 浏览工具树 → 检查 JSON Schema → 调用工具 资料来源：SKILL.md:23-31

访问控制与权限边界

为防止凭据滥用，Smithery 提供三层访问控制：命名空间（Namespace）、连接元数据（Metadata）与请求级（rpcReqMatch）精细限制。

命名空间作为工作区边界，对服务器、连接、技能进行隔离。文档建议每个应用或环境建立独立命名空间（如 my-app-dev、my-app-prod），通过 smithery namespace create / use 切换上下文 资料来源：SKILL.md:33-49

凭据策略通过 smithery auth token --policy 颁发短期服务令牌，单条约束内的字段为 AND 关系（更窄），多条约束或列表则为 OR 关系（更宽）。例如可限定某用户在其命名空间内仅能对特定连接进行 read 与 execute 操作 资料来源：SKILL.md:79-100

请求级工具限制是实验性能力，通过 rpcReqMatch 对 JSON-RPC 请求路径做正则匹配。需要特别注意：连接 ID 不会出现在 JSON-RPC body 中，因此必须与 metadata.connectionId 联合使用才能精确限定，例如将调用收缩到 issues.* 工具集 资料来源：SKILL.md:111-130

这种分层模型让代理既获得必要的调用面，又不会向不可信代码泄漏完整 API key，同时支持 --flat --limit 等管道友好的 JSONL 输出，便于在脚本链路中进行过滤与编排 资料来源：SKILL.md:131-135

1. 项目许可证

skill-smithery-ai-cli 采用 MIT 许可证分发。MIT 是最为宽松的开源许可证之一，允许在保留版权声明与许可声明的前提下自由使用、修改、再分发与商用。完整的许可证文本保存在仓库根目录的 LICENSE 文件中。

README.md 中的"License"小节以链接形式指向 LICENSE 文件，并简要说明本项目遵循的许可类型。package.json:license 字段以 SPDX 表达式声明，例如 "license": "MIT"，便于 npm 与其他包管理器在安装时自动识别并校验许可证兼容性。

2. 第三方依赖许可

项目通过 package.json 中的 dependencies 与 devDependencies 字段声明运行期与开发期依赖。每个依赖均自带各自的 LICENSE 文件，npm 在安装时会将其保留在 node_modules/<package>/LICENSE 路径下。

package.json:dependencies 列出了所有运行期依赖的版本约束。在合规审计中，可使用 npx license-checker 等工具扫描整个 node_modules 目录，自动汇总各依赖的许可证类型与版权信息。

3. 身份认证与 API 密钥

CLI 在调用 AI 服务时需要 API 密钥。仓库采用"环境变量 + .env 文件"的标准做法管理凭据，避免敏感信息写入源码或版本控制系统。

3.1 环境变量配置

.env.example 列出所有受支持的环境变量名，常见条目包括：

• 服务商 API 密钥（如 OPENAI_API_KEY）
• 可选的 API_BASE_URL 自定义网关
• 可选的 MODEL_NAME 模型选择

用户通过复制 .env.example 为 .env 并填入真实密钥完成配置。.env 文件应被 .gitignore 排除，禁止提交到远程仓库。

3.2 凭据加载流程

flowchart LR
    A[用户] -->|编辑 .env| B[加载环境变量]
    B --> C[src/auth.js 读取]
    C --> D{密钥存在?}
    D -->|否| E[报错并退出]
    D -->|是| F[附加 Authorization 头]
    F --> G[调用 AI 服务]

src/auth.js 是凭据加载与校验模块，负责：

• 从 process.env 读取密钥
• 在启动时校验密钥非空
• 构造 Authorization: Bearer <token> 头附加到出站请求
• 缺失密钥时输出明确错误并以非零状态码退出

README.md:Configuration 章节说明如何通过本地 .env、shell 环境变量或系统密钥管理器（如 macOS Keychain、Linux secret-tool）注入凭据。

4. 贡献者协议与安全披露

CONTRIBUTING.md 规定：

• 提交 Issue 与 Pull Request 的流程
• 代码风格与提交信息规范（通常遵循 Conventional Commits）
• 本地开发、构建与测试运行命令

CODE_OF_CONDUCT.md 采用 Contributor Covenant 模板，明确社区互动的基本准则，禁止任何形式的骚扰与歧视，并说明违规举报途径。

SECURITY.md 提供漏洞披露的安全联系方式，要求研究者在公开披露前通过私有渠道（例如 GitHub Security Advisories 或维护者邮箱）通知维护者，以便及时修复并协调披露时间。

总结

skill-smithery-ai-cli 在"授权与许可"层面遵循主流开源实践：自身采用 MIT 许可证分发；通过 package.json 与 node_modules 管理体系透明地声明第三方依赖许可；通过 .env 与 src/auth.js 实现 API 密钥的安全加载与传递；通过 CONTRIBUTING.md、CODE_OF_CONDUCT.md 与 SECURITY.md 完整覆盖贡献、行为与安全披露流程，形成清晰且合规的治理结构。

skill-smithery-ai-cli 是一个面向开发者的命令行工具，用于生成、管理和分发 AI Skill 文件（以 SKILL.md 为核心载体）。本页汇总在使用过程中常见的安装、配置、运行与生态集成问题，并给出基于仓库源码的排查思路。资料来源主要依据项目根目录的 README.md、SKILL.md、package.json、CHANGELOG.md 与 bin/skill-smithery.js。

1. 安装与环境问题

最常见的初次使用障碍集中在 Node.js 版本、依赖安装与全局注册三方面。

• Node.js 版本不兼容：仓库 package.json 中声明了 engines.node 字段以约束运行版本，低于该版本的 Node 会导致 CLI 启动失败或 ESM 语法报错。资料来源：package.json:12-18
• 依赖安装失败：若 npm install 抛出 EACCES 或 EAI_AGAIN，通常是全局目录权限或网络代理问题。可通过切换为 pnpm 或配置 npm config set registry 解决。资料来源：README.md:25-42
• 命令未识别（command not found）：执行 skill-smithery 提示找不到命令时，说明 bin 字段未链接到 PATH。需执行 npm link 或显式通过 npx skill-smithery 调用。资料来源：package.json:6-10, bin/skill-smithery.js:1-15

2. 配置文件与 SKILL.md 规范

CLI 在生成或校验 Skill 时严格依赖 SKILL.md 的元数据结构，配置错误往往导致模板解析失败。

• 缺少 frontmatter：每个 SKILL.md 顶部必须包含 YAML 头信息（name、description、version 等），缺失会触发 Missing required frontmatter 错误。资料来源：SKILL.md:3-18
• 字段命名不规范：字段名大小写敏感，例如 Name 与 name 在校验器中视为不同键。建议直接复用 README 中给出的 canonical 模板。资料来源：README.md:55-78
• 版本号格式：遵循 SemVer（MAJOR.MINOR.PATCH），非标准格式在 validate 子命令中会被拒绝。资料来源：SKILL.md:20-26

flowchart TD
    A[运行 CLI 子命令] --> B{读取 SKILL.md}
    B -->|文件不存在| C[报错: ENOENT]
    B -->|存在| D{解析 YAML frontmatter}
    D -->|字段缺失| E[报错: Missing field]
    D -->|格式非法| F[报错: Schema invalid]
    D -->|通过| G[执行业务逻辑]
    C --> H[排查: 文件路径/权限]
    E --> I[排查: 补全 YAML 字段]
    F --> J[排查: 对照 README 模板]

3. 运行时错误与网络请求

CLI 调用外部模型 API 时容易出现鉴权、配额与超时问题。

• API Key 未配置：当环境变量 SKILL_SMITHERY_API_KEY 未设置或为空时，子命令会返回 401 Unauthorized。需在 shell profile 或 .env 中注入。资料来源：README.md:80-102
• 请求超时：默认超时通常为 30 秒，可在配置文件中通过 timeoutMs 调整；频繁超时建议检查网络或切换端点。资料来源：SKILL.md:42-48
• 速率限制（429）：连续触发同一 provider 的限流时，CLI 不会自动重试，需手动退避或在 CHANGELOG 中确认是否已引入退避策略。资料来源：CHANGELOG.md:14-22

4. 发布与贡献相关问题

向社区发布或贡献 Skill 时的常见疑问集中在版本管理与 PR 流程。

• 版本号冲突：发布前需确认 package.json 的 version 与 SKILL.md 的 version 字段一致，避免 CI 检查失败。资料来源：package.json:3-5, SKILL.md:20-26
• PR 规范：贡献者应遵循 CONTRIBUTING.md 中关于提交信息、Skill 目录结构与文档同步更新的要求。资料来源：CONTRIBUTING.md:10-30
• 升级到新版后行为变更：升级后若发现子命令参数被废弃，应查阅 CHANGELOG.md 的 BREAKING CHANGE 段落，并按迁移指引调整脚本。资料来源：CHANGELOG.md:1-13

通用排查原则：先复现错误并捕获完整日志；其次对照 README.md 中的快速开始（Quick Start）验证最小可行流程；最后再深入到 SKILL.md 与源码 bin/skill-smithery.js 进行逐行定位。资料来源：README.md:1-24, SKILL.md:1-12, bin/skill-smithery.js:1-15

Pitfall Log / 踩坑日志

项目：chirag127/skill-smithery-ai-cli

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 skill-smithery-ai-cli 与安装入口 skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx skills
• 证据：identity.distribution | https://github.com/chirag127/skill-smithery-ai-cli | repo=skill-smithery-ai-cli; install=skills

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/chirag127/skill-smithery-ai-cli | host_targets=mcp_host, claude_code, claude

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/chirag127/skill-smithery-ai-cli | README/documentation is current enough for a first validation pass.

4. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/chirag127/skill-smithery-ai-cli | matched external service / cloud / webhook / database keyword

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/chirag127/skill-smithery-ai-cli | no_demo; severity=medium

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

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

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

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

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

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