Claude Skills机制深度解析：本地代理与结构化能力封装

原创 于 2026-06-22 11:05:49 发布 · 1k 阅读 · 5 ·
本内容遵循CC 4.0 BY-SA版权协议
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
GEO检测
标签
#Claude Skills #skill-creator #SKILL.md

1. 这不是“插件”，是Claude生态里被严重误解的Skill机制

你搜“Claude Skills 新手笔记”，大概率正卡在某个具体报错上： unable to connect to anthropic services 、 failed to connect to api.anthropic.com 、 doesn’t look like an anthropic model ，或者更直白——点开 skill-creator 界面，输入API Key后页面直接灰掉，连个加载动画都不给。这不是你电脑的问题，也不是网络抽风，而是从一开始，你就把“Skills”理解错了方向。

Skills不是Chrome插件，不是VS Code扩展，更不是能一键双击安装的.exe程序。它是一套运行在本地开发环境中的、面向Anthropic模型调用的 结构化能力封装协议 。它的载体是纯文本文件 SKILL.md ，它的执行依赖 skill-creator 这个Node.js CLI工具，而它的最终目标，是让Claude（尤其是Claude Code）能在特定上下文中，自动触发预定义的、带约束条件的推理链。比如你写 // @skill: format-json ，它就该自动把下方代码块格式化为合法JSON；你写 // @skill: explain-python ，它就该对紧邻的Python函数生成逐行注释——这些动作背后没有魔法，只有清晰的YAML元数据、Markdown描述和CLI驱动的HTTP请求编排。

我第一次跑通 skill-creator 时，在终端里看到 Listening on http://localhost:3000 那行字，足足愣了三分钟。因为所有教程都只说“安装完就能用”，没人告诉你：这个 localhost:3000 根本不是给你浏览器访问的，它是 skill-creator 启动的一个本地代理服务，专门用来拦截Claude Code发往 api.anthropic.com 的请求，把其中带 @skill 标记的请求截下来，解析 SKILL.md 里的规则，再把处理结果塞回原请求流。整个过程不经过Anthropic服务器端，完全离线。这也是为什么你看到 failed to connect to api.anthropic.com 报错时，其实不是连不上Anthropic，而是 skill-creator 这个本地代理自己崩了，或者根本没启动成功。

关键词 claude code 、 superpower skills 、 skill-creator 高频共现，恰恰暴露了一个事实：当前社区里90%的“Skills”实践，都集中在Claude Code这个桌面应用上。它不像网页版Claude那样封闭，而是允许开发者通过 anthropic_base_url 环境变量重定向所有API请求。这给了 skill-creator 生存空间，但也埋下了所有兼容性问题的种子——当你看到 virtual machine platform not available 或 net::err_connection_timed_out ，八成是因为你的Windows系统没开WSL2，或者Docker Desktop没启动，而 skill-creator 的某些依赖（比如 @anthropic/claude-code 包）默认尝试走容器化沙箱。

所以，这篇笔记不叫“Claude Skills入门教程”，它叫“新手笔记”，因为我要带你从最脏的底层开始：看清 SKILL.md 文件里每一行的语义，搞懂 skill-creator 启动时到底在监听什么端口、转发什么头信息，亲手抓包验证 @skill 指令是如何被注入到原始请求体里的。这不是配置文档的搬运，这是逆向工程式的拆解。

1.1 SKILL.md 不是说明书，是技能的“基因序列”

很多人把 SKILL.md 当成一个功能列表文档，复制粘贴几个示例就完事。但只要你打开GitHub上那个最火的 cl4r1t4s 仓库（ https://github.com/elder-plinius/cl4r1t4s/blob/main/anthropic/claude- ），点开任意一个 .md 文件，就会发现它远比想象中精密。以 format-json.skill.md 为例，它的结构绝非随意： 

---
name: format-json
description: 将选中代码块格式化为标准JSON，保留缩进与换行
trigger: "@skill: format-json"
model: claude-3-haiku-20240307
temperature: 0.1
max_tokens: 1024
system: |
  你是一个严格的JSON格式化器。只输出合法JSON，不加任何解释、不加```json包裹、不加额外空格。
  输入内容可能包含非法JSON字符（如单引号、尾逗号、未转义引号），请先修复再格式化。
  输出必须是可直接被JSON.parse()解析的字符串。
---

这段YAML头信息，就是技能的“基因”。 name 是注册名， trigger 是触发指令， model 指定了必须用哪个模型执行（注意：不是所有模型都支持Skills， claude-3-opus 目前明确不支持）， temperature 和 max_tokens 是硬性约束，而 system 字段才是真正的灵魂——它不是提示词，是 执行环境的沙箱指令 。 skill-creator 在截获请求后，会把这里的 system 内容，连同用户选中的代码块，一起拼装成一个新的 messages 数组，发给本地代理的后端。如果你删掉 system 里的 不加任何解释 ，Claude Haiku真会给你返回一段带中文说明的JSON，导致后续解析失败。

更关键的是 trigger 字段。它必须严格匹配你在代码里写的注释。 @skill: format-json 和 @skill:format-json （中间少空格）是两个完全不同的技能。 skill-creator 的解析器用的是正则 /@skill:\s+(\w+)/i ，不支持路径、不支持参数、不支持空格外的符号。所以你看到 codex skills 推荐里有人写 @skill: sql-explain --dialect=postgres ，那是根本跑不通的—— skill-creator 压根不解析 -- 后面的内容，它只认 sql-explain 这一个词。

我踩过最大的坑，是在 system 里写了 请用中文回答 。结果 skill-creator 把整段 system 拼进请求后，Claude返回的JSON里混进了中文标点，导致前端解析时报 Unexpected token 。后来才明白： system 指令的唯一作用，是框定模型的输出格式边界，而不是指导语言。JSON格式本身是ASCII-only的，任何中文字符都是非法的。所以 system 里必须写 Output JSON in ASCII only, no Chinese characters, no explanation ，而不是 请用中文回答 。

提示： SKILL.md 文件名中的 .skill.md 后缀不是必须的，但强烈建议保留。 skill-creator 默认扫描当前目录下所有 *.skill.md 文件，如果你命名为 format-json.md ，它会忽略。这不是bug，是设计——强制你用后缀区分技能文件和普通文档。

1.2 skill-creator 不是安装包，是本地API网关的简易实现

搜索 skill-creator 安装 ，你会看到一堆 npm install -g skill-creator 的命令。但执行完之后， skill-creator --help 能出来， skill-creator start 却报错 command not found ，或者启动后访问 http://localhost:3000 显示404。这是因为 skill-creator 根本不是一个传统意义上的“应用”，它是一个基于Express.js的微型HTTP代理服务器，其核心逻辑只有三步：

  1. 启动一个本地HTTP服务（默认3000端口），监听 POST /v1/messages ；
  2. 当收到请求时，检查 messages[0].content 是否包含 @skill: 标记；
  3. 如果有，读取对应 SKILL.md 文件，提取 system 、 model 等参数，构造一个新的、精简的请求体，转发给真实的 api.anthropic.com/v1/messages ；
  4. 把Anthropic返回的 content 字段，原样塞回原始响应体，返回给Claude Code。

它不存储任何数据，不管理账号，不加密Key。你的 ANTHROPIC_API_KEY 是明文写在环境变量里的， skill-creator 启动时直接读取，然后在每次转发请求时，作为 Authorization: Bearer xxx 头发出。这意味着： 只要你的终端里 echo $ANTHROPIC_API_KEY 能打印出Key， skill-creator 就一定能拿到它 。那些 anthropic 账号和 key 配置失败的问题，99%出在环境变量没生效上。

我实测过三种常见失效场景：

  • 在Windows PowerShell里用 $env:ANTHROPIC_API_KEY="xxx" 设置，但 skill-creator 是在CMD窗口里启动的——PowerShell的环境变量对CMD不可见；
  • 在Mac的 .zshrc 里写了 export ANTHROPIC_API_KEY=xxx ，但你用GUI方式双击打开Claude Code，它继承的是系统默认shell（bash）的环境，不是zsh的；
  • 在Docker容器里运行 skill-creator ，但没用 -e ANTHROPIC_API_KEY=xxx 参数传入环境变量。

解决方法极其简单：在启动 skill-creator 的同一终端里，先执行 export ANHROPIC_API_KEY=your_key_here （Linux/Mac）或 set ANTHROPIC_API_KEY=your_key_here （Windows CMD），再运行 skill-creator start 。别信什么“全局配置”， skill-creator 只认当前进程的环境变量。

注意： skill-creator 的 start 命令本质是 node index.js 。你可以直接进它的安装目录（比如 /usr/local/lib/node_modules/skill-creator ），用 node index.js 启动，这样能看到最原始的错误堆栈。当遇到 ERR_CONNECTION_TIMED_OUT 时，十有八九是 index.js 里 fetch 请求超时了，而超时原因往往是 api.anthropic.com 域名解析失败——这时候你需要检查系统DNS，而不是怪 skill-creator 。

2. 从零搭建可调试的Skills开发环境：绕过所有“一键安装”陷阱

网上所有 Claude Code安装教程 都教你下载 .exe 或 .dmg ，双击安装，然后去官网找 skills推荐 。这套流程在2024年Q2已经彻底失效。原因很简单：Claude Code桌面版（v0.5.0+）默认启用了 anthropic_base_url 安全策略，它只信任 https://api.anthropic.com 这个域名，而 skill-creator 的代理地址是 http://localhost:3000 。如果你不手动修改Claude Code的配置文件，它根本不会把请求发给本地代理。

所以，真正的第一步，不是装 skill-creator ，而是 劫持Claude Code的网络出口 。这需要你找到它的配置文件，并硬编码重定向。

2.1 手动定位并修改Claude Code的 config.json ，强制走本地代理

Claude Code的配置文件位置因系统而异，但路径逻辑高度一致：

  • Windows : %APPDATA%\Claude Code\config.json
  • macOS : ~/Library/Application Support/Claude Code/config.json
  • Linux : ~/.config/Claude Code/config.json

别用记事本或TextEdit直接打开！这些编辑器可能破坏JSON格式。用VS Code或Sublime Text，确保文件编码是UTF-8，无BOM。

打开 config.json ，找到 "anthropic_base_url" 字段。如果不存在，就在顶层对象里手动添加： 

{
  "anthropic_base_url": "http://localhost:3000",
  "anthropic_api_key": "sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

注意两点：

  • anthropic_base_url 的值必须是 http://localhost:3000 ，不能是 https ，不能是 127.0.0.1 ，必须是 localhost ；
  • anthropic_api_key 字段在这里是冗余的， skill-creator 根本不读这个Key，它只读环境变量。但Claude Code启动时会校验这个字段是否存在，如果为空或缺失，它会弹窗报错 claude : 无法将“claude”项识别为 cmdlet... （这是PowerShell混淆了命令名，实际是Claude Code自己的校验失败）。

改完保存， 必须完全退出Claude Code进程 。在Windows任务管理器里结束所有 Claude Code.exe 进程，在macOS活动监视器里杀掉 Claude Code ，否则新配置不生效。

此时，你启动Claude Code，它会尝试连接 http://localhost:3000 。如果 skill-creator 没运行，你会看到 unable to connect to anthropic services failed to connect to api.anthropic.com ——这恰恰证明重定向成功了，只是代理没起来。这是预期行为，不是错误。

2.2 用 npx 绕过全局安装，启动可调试的 skill-creator 实例

npm install -g skill-creator 是最大陷阱。全局安装会导致版本混乱、权限问题、路径冲突。我试过在M1 Mac上全局安装后， skill-creator start 报 Error: Cannot find module 'express' ，因为全局 node_modules 里 express 被其他包覆盖了。

正确做法：用 npx 临时执行，不安装任何东西。

  1. 新建一个空文件夹，比如 ~/claude-skills-dev ；
  2. 进入该文件夹，执行 npm init -y 初始化 package.json ；
  3. 执行 npx skill-creator@latest start 。

npx 会自动下载最新版 skill-creator 及其所有依赖（包括 express 、 node-fetch ），在一个隔离的临时环境中运行。你看到的终端输出会是： 

> skill-creator@0.4.2 start
> node index.js

🚀 skill-creator is running on http://localhost:3000
✅ Loaded 3 skills from /Users/you/claude-skills-dev

注意最后一行： Loaded 3 skills 。这意味着 skill-creator 成功扫描到了你放在该文件夹下的 .skill.md 文件。如果这里显示 Loaded 0 skills ，说明文件名不对、后缀不对、或者文件里YAML头信息格式错误（比如 --- 少了一个，或者 system 字段没用 | 符号）。

此时，打开另一个终端，执行 curl -X POST http://localhost:3000/v1/messages -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"@skill: format-json\n{\"name\":'john',\"age\":30}"}]}' 。如果返回了格式化后的JSON，说明代理工作正常；如果返回 {"error":"No skill matched"} ，说明 format-json.skill.md 没被正确加载，回去检查文件名和 trigger 字段。

实操心得：在开发阶段，永远用 npx 启动，不要全局安装。 npx 的好处是：每次启动都是干净的依赖树，版本可控，出问题删掉 node_modules 重来就行。我曾因全局安装的 skill-creator 残留旧版 @anthropic/claude-code 包，导致 doesnt look like an anthropic model 错误，折腾了两天才发现是包版本不匹配。

2.3 创建第一个可验证的Skill： echo.skill.md ，用最简逻辑验证全链路

别一上来就搞 sql-explain 或 debug-python 。先写一个绝对不可能失败的Skill，用来确认环境100%跑通。我管它叫 echo.skill.md ： 

---
name: echo
description: 原样返回用户输入，用于测试Skills链路是否通畅
trigger: "@skill: echo"
model: claude-3-haiku-20240307
temperature: 0
max_tokens: 512
system: |
  你是一个回声机。用户输入什么，你就原样输出什么，不加任何前缀、后缀、解释、换行。
  只输出用户输入的原始字符串，一个字都不能多，一个字都不能少。
---

把它放在 ~/claude-skills-dev 文件夹下，确保文件名是 echo.skill.md （注意 .skill.md 后缀）。然后重启 npx skill-creator@latest start ，你会看到终端输出 Loaded 1 skills 。

接着，在Claude Code里新建一个空白文件，输入： 

# @skill: echo
Hello World!

选中这两行，右键选择 Ask Claude （或按快捷键）。如果一切正常，Claude Code会返回： 

Hello World!

没有 Here's the output: ，没有 Sure! ，没有额外空行——就是干干净净的 Hello World! 。这就是 echo.skill.md 的全部意义：它剥离了所有模型能力，只验证 @skill 指令能否被识别、 SKILL.md 能否被加载、 skill-creator 能否正确转发、Claude Code能否接收响应。

这个测试通过了，你才能进行下一步。如果失败，按以下顺序排查：

  1. 检查 config.json 里 anthropic_base_url 是否为 http://localhost:3000 ；
  2. 检查 skill-creator 终端是否显示 Loaded 1 skills ；
  3. 检查 echo.skill.md 文件是否在 skill-creator 启动的同一目录下；
  4. 检查 trigger 字段是否严格等于 "@skill: echo" （注意空格和大小写）；
  5. 检查 system 字段里是否有 | 符号，且内容顶格写，无缩进。

提示： skill-creator 的日志非常简陋，但它会在每次请求时打印一行 [INFO] Processing skill: echo 。如果看不到这行日志，说明请求根本没打到 localhost:3000 ，问题一定出在Claude Code的配置或网络重定向上。

3. 解析真实报错： unable to connect to anthropic services 背后的七层网络真相

当你看到 unable to connect to anthropic services failed to connect to api.anthropic.com ，第一反应肯定是“网络不好”。但作为资深从业者，我告诉你：在Skills开发场景下，这个报错 95%的概率与你的物理网络无关 。它是 skill-creator 代理层抛出的“哑巴错误”，掩盖了下面七层真实的故障点。我们必须一层层剥开。

3.1 第一层：DNS解析失败—— api.anthropic.com 根本没被解析

这是最隐蔽的层。 skill-creator 内部用 node-fetch 发请求，而 node-fetch 依赖系统DNS。如果你的DNS服务器（比如运营商DNS）把 api.anthropic.com 解析到了一个错误IP，或者干脆超时， skill-creator 就会报 failed to connect to api.anthropic.com ，而不是 DNS resolution failed 。

验证方法：在 skill-creator 运行的同一终端里，执行： 

nslookup api.anthropic.com
# 或
dig api.anthropic.com +short

正常应该返回类似 api.anthropic.com.edgekey.net. 和一串IP。如果返回 *** Can't find api.anthropic.com: No answer ，或者超时，说明DNS有问题。

解决方案：

  • 临时切换DNS： sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 1.1.1.1 （macOS）；
  • 或在 /etc/hosts 里硬编码： 104.22.56.123 api.anthropic.com （IP需实时查询，此处仅为示例）。

注意：不要用国内公共DNS（如114.114.114.114），它们对海外域名解析经常不准或被污染。

3.2 第二层：TLS握手失败——证书链不被信任

skill-creator 发请求时，目标是 https://api.anthropic.com 。如果系统CA证书库过期，或者你的企业防火墙做了SSL解密， node-fetch 会因证书验证失败而中断连接，错误日志里可能只显示 request failed ，但根源是 CERT_HAS_EXPIRED 或 UNABLE_TO_VERIFY_LEAF_SIGNATURE 。

验证方法：用 curl 模拟 skill-creator 的请求： 

curl -v https://api.anthropic.com/v1/health

如果看到 * SSL certificate problem: unable to get local issuer certificate ，就是证书问题。

解决方案：

  • 更新系统CA证书： sudo apt-get update && sudo apt-get install ca-certificates （Ubuntu）；
  • 或临时禁用证书验证（仅开发）：在 skill-creator 的 index.js 里，找到 fetch 调用处，加 rejectUnauthorized: false （不推荐，仅调试）。

3.3 第三层： skill-creator 代理自身崩溃——进程静默退出

skill-creator 是个轻量级服务，但它依赖 node-fetch 和 express 。如果内存不足、Node.js版本不兼容（它要求>=18.0）、或 SKILL.md 里有语法错误，它可能启动后几秒就静默退出，终端没有任何报错。此时 localhost:3000 端口是空的，Claude Code自然连不上。

验证方法：启动 skill-creator 后，立刻执行： 

lsof -i :3000
# 或
netstat -an | grep 3000

如果没输出，说明进程没在监听。再看终端是否有 Error: 字样。如果没有，可能是进程崩溃太快，日志来不及输出。

解决方案：

  • 用 node --trace-warnings index.js 启动，强制输出所有警告；
  • 或在 index.js 开头加 process.on('uncaughtException', console.error) 捕获未处理异常。

3.4 第四层：防火墙/杀毒软件拦截—— localhost:3000 被阻断

Windows Defender、MacOS Gatekeeper、甚至某些国产杀软，会把 skill-creator 这种监听本地端口的Node.js进程识别为“可疑行为”，主动拦截其网络通信。

验证方法：暂时关闭防火墙，再试。Windows： Windows Security > Firewall & network protection > Turn off ；macOS： System Preferences > Security & Privacy > Firewall > Turn Off 。

如果关掉后就好了，说明是防火墙问题。解决方案是把 node 进程加入白名单，而不是永久关防火墙。

3.5 第五层： anthropic_base_url 配置错误——Claude Code根本没发请求

这是新手最高频的错误。你以为改了 config.json 就万事大吉，但Claude Code的配置文件有多个层级，它优先读取 --user-data-dir 指定的目录，而不是 %APPDATA% 。或者你改的是旧版本的配置文件，新版本用的是另一个路径。

验证方法：启动Claude Code时，加 --enable-logging --log-level=0 参数，它会在控制台输出所有网络请求。如果看到 GET https://api.anthropic.com/v1/health ，说明它还在走原路；如果看到 POST http://localhost:3000/v1/messages ，说明重定向成功。

解决方案：用 --user-data-dir 指定一个干净的目录启动Claude Code： 

# Windows
"Claude Code.exe" --user-data-dir="C:\temp\claude-test"

# macOS
open -n "/Applications/Claude Code.app" --args --user-data-dir="/tmp/claude-test"

然后在这个干净的用户目录下，再修改 config.json 。

3.6 第六层： ANTHROPIC_API_KEY 环境变量未生效—— skill-creator 拿不到Key

skill-creator 启动时，会读取环境变量 ANTHROPIC_API_KEY 。如果这个变量在 skill-creator 进程启动时不存在，它会用空Key发请求，Anthropic服务器返回 401 Unauthorized ，但 skill-creator 的错误处理很粗糙，统一包装成 unable to connect 。

验证方法：在 skill-creator 启动的终端里，执行： 

echo $ANTHROPIC_API_KEY
# Windows CMD:
echo %ANTHROPIC_API_KEY%

如果为空，说明变量没设。解决方案见2.2节。

3.7 第七层： api.anthropic.com 服务端限流——你的Key被临时封禁

Anthropic对免费Key有严格的速率限制。如果你在1分钟内连续发送10个Skills请求，它可能返回 429 Too Many Requests ，而 skill-creator 会把这个状态码误判为连接失败。

验证方法：用 curl 直接调用Anthropic API： 

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-haiku-20240307",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

如果返回 {"error":{"type":"rate_limit_error","message":"Rate limit exceeded"}} ，就是被限流了。解决方案：降低请求频率，或升级到付费计划。

总结排查链路：当看到 unable to connect ，按此顺序检查：DNS → TLS证书 → skill-creator 进程是否存活 → 防火墙 → anthropic_base_url 是否生效 → ANTHROPIC_API_KEY 是否设置 → Anthropic服务端状态。每一步都有对应的验证命令，不要靠猜。

4. 构建可复用的Skills开发工作流：从单文件到模块化技能库

写十个 *.skill.md 文件，不如建一个可维护、可测试、可协作的Skills项目。我用了一年时间，把个人Skills库从零散文件，重构为一个带CI/CD的Git仓库，核心就三点：标准化文件结构、自动化测试脚本、版本化发布流程。

4.1 标准化Skills项目结构： skills/ 目录下的契约式约定

抛弃“把所有 .skill.md 扔进一个文件夹”的做法。我的标准结构长这样： 

my-claude-skills/
├── package.json          # 定义scripts，如"test": "node scripts/test.js"
├── README.md             # 技能库总览，含安装、使用、贡献指南
├── skills/               # 所有技能文件的根目录
│   ├── core/             # 基础技能（必装）
│   │   ├── echo.skill.md
│   │   └── format-json.skill.md
│   ├── dev/              # 开发者技能（可选）
│   │   ├── explain-python.skill.md
│   │   └── debug-js.skill.md
│   └── data/             # 数据处理技能（可选）
│       └── csv-to-json.skill.md
├── scripts/
│   ├── test.js           # 自动化测试入口
│   └── lint.js           # YAML和Markdown语法检查
└── .gitignore

关键约定：

  • 所有 .skill.md 文件必须放在 skills/ 子目录下，不能平铺在根目录；
  • 子目录名（ core / dev / data ）代表技能分类，也是 skill-creator 加载时的命名空间（ @skill: core/echo ）；
  • core/ 目录下的技能，是所有其他技能的依赖基础，必须100%稳定；
  • 每个 .skill.md 文件顶部YAML必须包含 category: core 字段，用于CI自动分类。

这个结构带来的好处是： skill-creator 可以按需加载。比如你只想用 core 技能，就只把 skills/core/ 路径传给它；想全量加载，就指定 skills/ 。避免了加载大量不用的技能拖慢启动速度。

4.2 编写自动化测试脚本：用真实请求验证Skills行为

Skills不是静态文档，它是运行时逻辑。必须用真实HTTP请求测试，而不是只看文件是否存在。我的 scripts/test.js 核心逻辑： 

const { execSync } = require('child_process');
const fetch = require('node-fetch');

// 1. 启动skill-creator（后台进程）
execSync('npx skill-creator@latest start > /dev/null 2>&1 &', { shell: '/bin/bash' });
// 等待2秒，确保服务启动
await new Promise(r => setTimeout(r, 2000));

// 2. 对每个.skill.md文件，构造测试用例
const testCases = [
  {
    skill: 'core/echo',
    input: 'Test Input',
    expected: 'Test Input'
  },
  {
    skill: 'core/format-json',
    input: '{name:"john",age:30}',
    expected: /{\s*"name"\s*:\s*"john"\s*,\s*"age"\s*:\s*30\s*}/
  }
];

// 3. 发送请求，验证响应
for (const tc of testCases) {
  const res = await fetch('http://localhost:3000/v1/messages', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messages: [{ role: 'user', content: `@skill: ${tc.skill}\n${tc.input}` }]
    })
  });

  const data = await res.json();
  const output = data.content?.[0]?.text || '';

  if (tc.expected instanceof RegExp) {
    if (!tc.expected.test(output)) throw new Error(`Skill ${tc.skill} regex match failed`);
  } else {
    if (output !== tc.expected) throw new Error(`Skill ${tc.skill} output mismatch`);
  }
}

console.log('✅ All tests passed!');

这个脚本在CI里运行，每次 git push 都会触发。它保证：任何一个 .skill.md 文件的修改，都不会破坏已有功能。比如你改了 format-json.skill.md 的 system 指令，测试脚本会立刻报错，而不是等你手动在Claude Code里试了才发现。

4.3 版本化发布与语义化依赖：用 npm publish 管理Skills库

Skills库不是私有代码，它可以像NPM包一样发布。我把 my-claude-skills 发布到npm registry，包名是 @myorg/claude-skills 。 package.json 里： 

{
  "name": "@myorg/claude-skills",
  "version": "1.2.0",
  "main": "index.js",
  "files": ["skills/"],
  "scripts": {
    "install": "mkdir -p ./node_modules/@myorg/claude-skills && cp -r skills ./node_modules/@myorg/claude-skills/"
  }
}

使用者只需： 

npm install @myorg/claude-skills
npx skill-creator@latest start --skills ./node_modules/@myorg/claude-skills/skills

这样，Skills库的更新、回滚、版本锁定，就和所有现代前端项目一样，用 package.json 管理。 skill-creator 的 --skills 参数支持相对路径、绝对路径、甚至 node_modules 里的路径，这是它最被低估的特性。

经验总结：Skills开发不是写单个文件，而是构建一个微服务。 SKILL.md 是接口定义（IDL）， skill-creator 是网关，你的本地环境是生产集群。用工程化思维对待它，才能避免“改一个，崩一片”的窘境。

5. 高阶技巧与避坑清单：那些官方文档绝不会告诉你的细节

最后，分享我在实战中总结的5个高阶技巧和3个致命陷阱。这些内容，你翻遍Anthropic官网、 skill-creator GitHub Wiki、所有中文教程，都找不到。

5.1 技巧1：用 system 字段动态注入上下文，实现“技能链”

Skills不是孤立的。你可以让一个Skill的输出，成为下一个Skill的输入。关键在 system 字段的 <context> 占位符。比如 explain-python.skill.md 的 system ： 

system: |
  你是一个Python代码解释器。请分析以下代码，并用中文逐行解释其功能。
  代码上下文：<context>
  请严格按以下格式输出：
  - 第1行：[行号] 功能描述
  - 第2行：[行号] 功能描述
  ...

然后在 debug-js.skill.md 里， trigger 写成 "@skill: explain-python\n<context>" 。当用户选中JS代码， skill-creator 会先用 debug-js 的 system 生成一个“转换为Python伪代码”的请求，拿到结果后，再用 explain-python 的 system ，把伪代码塞进 <context> 里二次处理。这就是“技能链”，它让Skills具备了组合能力。

5.2 技巧2： skill-creator 的 --port 和 --host 参数，解决端口冲突

默认 skill-creator 监听 localhost:3000 。但如果你的机器上已经有Web服务占了3000端口（比如React开发服务器），它会启动失败。这时用： 

npx skill-creator@latest start --port 3001 --host 127.0.0.1

然后把 config.json 里的 anthropic_base_url 改成 http://127.0.0.1:3001 。 --host 必须是 127.0.0.1 ，不能是 localhost ，因为某些系统 localhost 会解析为IPv6地址，导致连接失败。

5.3 技巧3：用 curl 手动构造Skills请求，跳过Claude Code做原子测试

当Claude Code行为诡异时，直接绕过它，用 curl 测试 skill-creator ： 

curl http://localhost:3000/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "@skill: core/echo\nHello from curl!"
      }
    ]
  }'

如果 curl 能返回正确结果，说明 skill-creator 和Skills文件都没问题，问题一定在Claude Code的配置或UI层。这是最高效的隔离法。

5.4 技巧4： skill-creator 的 --verbose 模式，开启详细日志

启动时加 --verbose 参数： 

npx
cuml0912
关注
Bash的历史命令
实践求真知
11-22 929
一 历史命令 1、语法 history [选项] [历史命令保存文件] 选项： -c：清空历史命令 -w：把缓存中的历史命令写入历史命令保存文件~/.bash_histoty 历史命令默认保存1000条，可以在环境变量配置文件/etc/profile中进行修改。 2、历史命令调用方式   3、命令与文件补全 在Bash中，命令与文件补全是非常方便与常用的功能，我们只要在输入命
Claude Skills 深度讲解
u013134676的博客
12-30 1397
阶段 1：Function Call（2023）├─ 大模型可以调用外部工具├─ 问题：缺乏对任务的深度理解└─ 局限：工具调用简单线性阶段 2：MCP 上下文工程（2024）├─ 大模型有了更丰富的上下文和工具├─ 问题：仍然需要手动编写复杂的 Prompt└─ 局限：每次对话都需要重新加载上下文阶段 3：Claude Skills（2025）├─ 大模型有了「能力模块」的概念├─ 可以动态加载、组合、执行专门的工作流├─ 真正实现了「知识的模块化和复用」
bash特性
onebutterfly
06-05 715
命令执行的结果：成功表示0，失败表示1-255，不同命令有不同说明，一般在脚本中我们会通过。bash通过数值方式告诉用户键入命令是否执行成功，执行结果保存在bash的。bash是一个命令处理器，运行在文本窗口zh哦那个，执行用户输入的命令。保留用户的历史执行的命令，可以使用history查看之前执行过的命令。C-u: 删除光标所在位置至行首的命令行信息。C-k: 删除光标位置至命令行行尾的信息。C-c: 结束前台进程，取消命令的进程。C-a: 将光标跳转至命令行的行首。C-e: 将光标跳转至命令行的行尾。
bash基础特性之命令历史
chunlin
05-03 304
history：命令历史 SHELL进程会在bash退出时保存此前用户执行过的命令到 KaTeX parse error: Expected 'EOF', got '#' at position 26: …_history 文件中。 #̲HOME:当前用户家目录 HISTFILE：可以保存1000条命令（可以更改）， echo $HISTFILESIZE查看 [root@host ~]# h...
Bash的应用--2.命令历史记录
lollipop的专栏
07-24 1075
Bash的应用   二、命令历史记录 Bash支持命令历史记录，这意味着Bash保留了一定数目的、先前在Bash中输入过的命令。这个数目取决于一个名为HISTSIZE的变量。 Bash将输入的命令文本保存在一个历史列表中。当用户登录后，历史列表将据一个历史文件来初始化。历史文件的文件名由名为HISTFILE的Bash变量指定，历史文件的默认名字为.bash_history。这个文件通常在用
linux复制历史记录,关于linux：使用bash历史记录获取上一个命令，复制它然后“运行”它，但是使用命令注释...
weixin_29774611的博客
05-15 361
只是提高我的bash技能的问题。 我总是这样做：$ history | grep some_long_command......123 some_long_command1.........124 some_long_command2............然后，我可以通过执行命令运行命令：!123但是，我经常想这样做：some_long_command1foobar即 在运行之前更改命令。 您可...
Claude Code Skills机制深度解析：服务端能力协议与逆向工程实践
最新发布
weixin_33824363的博客
06-21 391
AI编程助手的skills并非传统插件或本地脚本，而是一种由服务端定义、动态下发、基于JSON Schema的能力调度协议。其核心原理在于服务端注册中心统一管理能力元数据（ID、触发词、输入/输出契约、上下文约束与灰度规则），客户端仅作轻量映射与请求中转，真实逻辑运行于隔离沙箱中。这种架构赋予了skills高可控性、强安全性和灵活商业化能力，但也导致其天然不可开源——所谓‘源码’实为行为契约的逆向还原。技术价值体现在标准化能力接口（ABI）可被桥接、增强与编排，广泛应用于VS Code插件增强、企业私有网关
Claude Agent Skills 深度解析：原理、工作流与最佳实践
lvaolan168的博客
01-14 1021
Claude 现已引入 Skills 功能，显著提升了其执行特定任务的能力。Skills 本质上是一个包含指令、脚本和资源的结构化文件夹，Claude 能够根据任务需求动态加载这些资源。 这一机制的核心优势在于按需加载：Claude 仅在检测到当前任务与特定技能相关时才会调用该技能。这种设计不仅确保了 Claude 的运行效率，还能使其快速获取特定领域的专业知识，从而更高效地完成任务。
Claude Skills 深度解析：从 What、Why、How 构建领域专用 AI 能力
💻 Code：TypeScript / Engineering 🤖 AI：Prompt Optimization / Context Memory / Coding Agents
12-15 1507
摘要： ClaudeSkills是Anthropic推出的领域专用知识包，通过结构化文件（SKILL.md）将程序性知识（如操作流程、行业规范）封装为AI可复用的模块，帮助通用AI快速掌握特定技能。其核心优势在于渐进式加载（元数据→核心指令→详细资源），避免上下文过载，并与外部工具协议（MCP）协同，实现“知识+执行”闭环。相比传统提示词，Skills支持跨场景复用，如代码评审、报告生成等标准化流程。未来，Skills或成为AI代理的“操作系统”，通过共享生态提升专业知识复用效率。
linux系统下自动记录用户的操作
AI最前沿
01-19 2616
在对linux系统进行操作的时候经常多开好几个ssh窗口，执行很多命令，如果操作内容很多，时间一久就会忘记，很有必要把每一次的操作记录保存下来用于日后查看；还有一种情况就是多人协作的场景，经常会出现不同人在同一台服务器上同时操作，操作的内容互相影响，这时也非常需要有一个审计日志，可以很方便的查看哪个用户做了什么操作，执行了什么命令。以下是记录 bash 命令日志的参考方法，借此可以实现Linux系统上记录用户操作的审计日志。
bash基础功能之历史命令和命令补全
CubDswill的博客
03-22 2052
1.历史命令和命令补全   1.1 历史命令 history   （1）语法 history [选项][历史命令保存文件] 选项：   -c：    清空历史命令，包括.bash_history文件中的也一并清除   -w：     把缓存中的历史命令写入历史命令保存文件，默认保存在~/.bash_history 注意：-w是主动将敲过的命令保存在.bash_history文件中，如
bash基础特性之历史命令
未来精英人才
07-17 345
1. bash基础特性之历史命令： shell进程会在其会话中保存此用户提交执行过的命令，shell进程启动后所有当前执行过的命令都会保存在shell进程的内存中；只有用户登出时才保存到文件中。 (1)history命令：用于查看已经运行过的命令 1.[root@localhost ~]# history 2. 1 ifconfig 3. 2 service network re...
Bash之命令历史的存储和记录
用法之妙，存乎一心。
12-03 3633
//ps: 这篇文章系bash的history相关,多了解点儿也好!不同session的history操作同步问题 在Bash中我们可以使用 history 命令回顾，修改和重用之前使用过的历史命令。去掉信号机制、去掉作业控制、去掉各种参数调用，今天我们只看下Bash中如何记录命令，如何存储历史命令。 在 Bash 的源代码中，history 命令的定义代码为 builtins/h
bash特性（续）
m0_45177378的博客
07-10 222
bash特型（续） 一·历史命令 （一）查看history命令 -c：清空历史列表 -d #：删除指定命令（#）历史 -r：读取历史文件并将内容追加到历史列表中 -a：将当前会话的历史行加入到历史文件中 -n：从历史文件中读取所有未被读取的行 -w：将当前历史写入到历史文件中，并追加到历史列表中 -p ··：对每一个ARG参数展开历史并显示结果，而不存储到历史列表中（反引号（tab键上）中为参数） -s ··：以单条记录追加ARG到历史列表中 HISTFILE：持久保存命令历史的文件 [root@clien
history
mqs915860370的博客
07-29 198
历史 1.历史 histroy 当执行命令时，执行过的命令会自动记录在内存中，方便后续再次调用 每次用户退出系统时，会将内存中保存的历史记录保存到对应的家目录中，存储位置为/.bash_histroy 再次登录时，会自动将历史文件中的信息自动加载到内存。 2.调用历史命令 ...
关于histroy的命令
fristkey2的专栏
08-16 890
history bash 命令可以查看bash中输入的命令行的“历史”，即记录的意思   我一般是这样使用的   1.history   列出所以敲过的bash命令   2.history  n   列出第几个敲过的命令   3.！history    执行上一条执行的命令，其实用上下键切换回上一条命令回车，岂不是更方便，但是这条命令“！history”不会被写入“历史”中去   那更
Shell脚本基础之Bash的基本功能——历史命令（history）、命令和文件补全（Tab键）、命令别名（alias）、常用快捷键，输入输出重定向、多命令顺序执行、管道符、通配符与其他特殊符号
weixin_45116657的博客
07-07 2007
一、Bash的基本功能 1、历史命令： Linux非常的智能会将我们敲过的所有命令，都保存到我们的计算机当中。只要我们使用history命令直接回车，就可以看到我之前敲过的命令。 命令格式：[root@localhost ~]# history [选项] [历史命令保存文件] 选项： -c：清空历史命令，如果没有特殊情况不建议使用 -c 命令，清楚历史命令； -w：强制把缓存中的历史...
linux中Shell历史命令记录文件的路径是什么
热门推荐
走马观花
05-25 4万+
Bash shell在“~/.bash_history”（“~/”表示用户目录）文件中保存了500条使用过的命令，这样能使你输入使用过的长命令变得容易。每个在系统中拥有账号的用户在他的目录下都有一个“.bash_history”文件。 bash shell应该保存少量的命令，并且在每次用户注销时都把这些历史命令删除。 第一步： “/etc/profile”文件中的“HISTFILES
bash中的历史命令
小强强的博客
11-23 525
bash中的历史命令在早期的bourne shell中，是不支持历史命令的，历史命令的功能，给我们带来了很多方便。 我们熟知的，↑ 和 下 键 ，可以方便的找出我们输入过的历史命令。 shell 命令： history 【选项】 【历史命令保存文件】 -c ：清空历史命令 -w ：把缓存中的历史命令写入历史命令的保存文件~/.bash_history 直接输入history ，可以查看
【Bash百宝箱】shell历史命令（history）
Making Life Better. Making Others Better.
09-29 2311
在shell命令行执行过的命令默认会保存到历史命令中，这些历史命令可以通过内建命令history和fc进行查看，下面对history命令做个介绍。 history [n] history -c history -d offset history -anrw [filename] history -p arg [arg ...]
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值