1. 为什么要在 AtomCode 里写自定义斜杠命令AtomCode 的 Skills 机制简单说就是让你用一份SKILL.md文件把「一段固定意图 一组参数 一段执行逻辑」打包成一个斜杠命令。你在编辑器对话框里敲/weather 北京AtomCode 会去 Skills Registry 里找同名 Skill读取它的元数据、参数定义和系统提示词然后把结果按你定义的格式吐回来。它适合谁三类人最明显。第一类是每天重复同样几段提示词的开发者比如「把这段 JSON 转成 TypeScript 接口」「按团队规范生成 commit message」与其每次手打不如固化成一个/gen-type。第二类是想把内部 API、脚本、数据查询接进编辑器的团队Skill 就是最轻的入口不用起服务、不用写协议。第三类是已经在用 MCP 的人Skill 可以作为「用户入口层」复杂能力再往下透传给 MCP Server。Skills 和 MCP 不是替代关系。MCP 更像一套跨平台的工具调用协议能力重、需要独立进程Skill 是 AtomCode 进程内的声明式扩展成本低、上手快。我试过的组合方式是简单、高频、参数少的场景用 Skill 直接搞定需要连数据库、连外部服务、要跨客户端复用的用 Skill 做入口内部再调 MCP Tool。这样既保留了斜杠命令的顺手又不至于把复杂逻辑塞进 Markdown。下面从目录结构开始一步步跑通一个最小可用 Skill再补上参数校验、错误处理和验证请求的完整链路。2. TaoToken 前置把模型调用通道先备好Skill 本身只负责「命令解析 逻辑编排」真正干活的那次 LLM 调用需要一个稳定的模型通道。AtomCode 里配置模型供应商时我一般用 TaoToken 作为统一入口它的 API 地址是https://taotoken.net/api兼容主流协议格式配置项少适合放在 Skill 开发这种需要频繁调试的场景里。你需要先拿到一个 API Key。打开https://taotoken.net/api-keys登录后创建一个 Key复制出来。注意 Key 只在创建时完整显示一次丢了就重新建一个。拿到 Key 之后在 AtomCode 的模型配置里填入。不同版本配置入口略有差异核心是三项Base URL 填https://taotoken.net/apiAPI Key 填你刚复制的那串模型名按你账号下可用的填。配完可以先在模型对话里发一句「你好」验证通道是否通通了再往下写 Skill能省掉一半排障时间。如果你打算长期做编码类 Skill、或者要跑 Agent 循环可以顺带了解下 Coding Plan它在高频调用下比按次计费更划算。入口在https://taotoken.net/coding-plan。这一步不是必须的但如果你一天要触发几十次 Skill 调试提前配好能少很多中断。注意API Key 不要硬编码进SKILL.md或执行脚本里。脚本里用环境变量读取比如${WEATHER_API_KEY}这种写法AtomCode 执行时会从环境注入。3. 可复制配置SKILL.md 骨架与目录结构3.1 目录结构Skill 的最小单元就是一个目录里面至少有一个SKILL.md。需要执行外部脚本时再加一个入口文件。我习惯这样组织# 创建 Skill 目录 mkdir -p ~/.atomcode/skills/weather cd ~/.atomcode/skills/weather # 目录结构 # weather/ # ├── SKILL.md # Skill 配置与提示词 # ├── main.py # 执行脚本可选 # └── README.md # 说明文档可选~/.atomcode/skills/是本地 Skill 的默认扫描路径放进去之后用注册命令让它生效。3.2 SKILL.md 骨架SKILL.md用 Markdown 写头部是一段 YAML front matter下面分Parameters、Logic、System Prompt几个区块。下面这份是可以直接复制改的骨架--- name: weather description: 查询指定城市的实时天气和未来天气预报 version: 1.0.0 author: your-name tags: [weather, tool, api] --- ## Parameters - city: string - description: 要查询天气的城市名称 - required: true - example: 北京 - minLength: 2 - maxLength: 50 - days: number - description: 预报天数1-7天 - required: false - default: 3 - minimum: 1 - maximum: 7 - unit: enum - description: 温度单位 - values: [celsius, fahrenheit] - default: celsius ## Logic 1. 接收用户输入的城市名称 2. 调用天气 API 获取数据 3. 解析返回的 JSON 4. 按参数格式化输出 ## System Prompt 你是一个专业的天气助手。当用户查询天气时你需要 1. 确认城市名称的准确性 2. 提供当前天气状况温度、湿度、风向等 3. 提供未来几天的天气预报 4. 给出适当的穿衣和出行建议几个关键字段的作用name决定斜杠命令的名字name: weather对应/weatherdescription会出现在命令补全列表里写清楚用途version用语义化版本方便后续分发Parameters里的required、default、minimum、maximum、values这些约束AtomCode 会在执行前自动校验。3.3 命令注册配置写完SKILL.md后用 CLI 注册到本地 Registry# 注册 Skill atomcode skill register ~/.atomcode/skills/weather # 查看已注册列表 atomcode skill list # 输出示例 # NAME VERSION AUTHOR DESCRIPTION # weather 1.0.0 your-name 查询指定城市的实时天气...注册成功后/weather就会出现在编辑器的斜杠命令补全里。如果没出现先确认SKILL.md的 front matter 格式是否正确YAML 对缩进敏感冒号后面要有空格。4. 验证请求从触发命令到拿到结果4.1 本地测试命令注册完先别急着在编辑器里点用 CLI 直接测一次能快速定位是配置问题还是逻辑问题# 测试 Skill传入参数 atomcode skill test weather --params {city: 北京, days: 3}如果 Skill 里带了执行脚本AtomCode 会把参数以 JSON 形式通过sys.argv[1]传给脚本。脚本的入口大致长这样#!/usr/bin/env python3 # weather/main.py import sys import json def main(): # 读取 AtomCode 传入的参数 params json.loads(sys.argv[1]) if len(sys.argv) 1 else {} city params.get(city, 北京) days params.get(days, 3) unit params.get(unit, celsius) # 这里替换成真实的 API 调用逻辑 result f{city} 未来 {days} 天天气单位 {unit} print(result) if __name__ __main__: main()4.2 成功结果长什么样执行atomcode skill test后预期输出类似☀ 北京 天气预报 ────────────────────── 当前天气 天气状况: 晴 温度: 25°C 体感温度: 27°C 湿度: 45% 风向: 东南风 3级 未来 3 天预报 07月05日 | 晴 | 32° / 22° 07月06日 | 多云 | 30° / 21° 07月07日 | 小雨 | 28° / 20° 生活建议 穿衣: 天气炎热建议穿轻薄透气的衣物 带伞: 无需带伞看到这段输出说明从命令解析、参数注入、脚本执行到结果回显的整条链路都通了。接下来在编辑器对话框里敲/weather 上海应该能拿到同样格式的结果。4.3 参数校验的验证故意传一个不合法的参数验证校验是否生效# days 超出范围应该被拦截 atomcode skill test weather --params {city: 北京, days: 99}预期返回参数校验错误提示days超出maximum: 7。如果没拦截检查SKILL.md里days的maximum是否写对以及缩进是否在days这个参数块下面。5. 本篇常见错排查5.1 斜杠命令不出现最常见的原因是SKILL.md的 front matter 没解析成功。YAML 要求---独占一行字段冒号后必须有空格。另一个原因是注册路径写错atomcode skill register后面跟的应该是 Skill 目录不是SKILL.md文件本身。5.2 参数传不进去脚本里读参数的方式要和 AtomCode 的注入方式对齐。当前版本是把参数序列化成 JSON 放在sys.argv[1]如果你按位置参数去读sys.argv[1]、sys.argv[2]就会拿到一整串 JSON 而不是单个值。统一用json.loads(sys.argv[1])再取字段。5.3 执行脚本报权限错误Linux/macOS 下脚本需要可执行权限chmod x ~/.atomcode/skills/weather/main.py另外脚本首行的 shebang 要写对Python 脚本用#!/usr/bin/env python3别写成硬编码路径。5.4 环境变量读不到SKILL.md里写${WEATHER_API_KEY}这种占位符AtomCode 执行时会尝试从环境注入。如果读不到先确认环境变量在当前 shell 会话里已 export再重启 AtomCode 让配置生效。不要把 Key 直接写死在脚本里既不安全分发时也容易泄露。5.5 输出格式乱掉System Prompt里定义的输出模板和脚本实际print的内容要一致。如果脚本直接输出原始 JSON而提示词里写的是格式化文本模型可能会二次加工导致格式漂移。建议脚本负责结构化数据格式化交给提示词或者反过来别两边都做。6. 继续往下走接入文档与模型验证跑通最小 Skill 之后下一步通常是把它接到真实能力上。如果你要调外部 API先确认 Key 和网络通道没问题TaoToken 的接入文档在https://taotoken.net/doc里面有各协议的请求示例照着改脚本里的请求部分就行。验证模型通道是否正常用模型对话最快发一句带参数的指令看返回是否符合预期。如果你打算把 Skill 用在长期编码或 Agent 循环里Coding Plan 的额度模型更适合高频触发场景入口在https://taotoken.net/coding-plan。Skill 开发这件事坑基本都集中在「配置格式」和「参数注入」两处逻辑本身反而简单。把这两块跑顺后面加多少个自定义斜杠命令都是复制粘贴改字段的活。