1. QwenCode Skill 配置骨架settings.json 与 SKILL.md 到底怎么落地QwenCode 的 Skill 机制说白了就是给 AI 装“专业技能包”。你问天气它翻天气技能包你让它整理 Excel它翻数据统计技能包。核心就两个文件settings.json负责开关和权限SKILL.md负责写清楚这个技能该怎么干活。适合谁适合那些不想写复杂代码、但想让 AI 按固定套路处理重复工作的人比如每周整理借样数据、每天查天气穿衣建议、批量重命名文件这类场景。我试过在 Win11 上从零配一个天气 Skill踩过几个坑比如allowedTools没写对导致工具调不起来、SKILL.md的description写得太模糊导致 AI 不触发。下面把可复制的骨架和验证步骤完整拆一遍。先明确两个文件的位置。QwenCode 安装完后用户目录下会有一个.qwen文件夹。Win11 快速访问按Win R输入%USERPROFILE%\.qwen回车。里面结构大致是.qwen/ ├── settings.json # 核心配置模型、API Key、实验特性 └── skills/ # 自定义技能文件夹 └── weather-advisor/ └── SKILL.mdsettings.json是全局配置skills/下每个子文件夹就是一个独立技能。Skill 的触发逻辑是你输入一句话AI 先做意图识别然后扫描skills/下所有SKILL.md的description字段匹配上了就按那个技能里的指令执行匹配不上就走通用能力。所以description写得好不好直接决定技能会不会被触发。这里有个关键点allowedTools是权限白名单。你不写AI 可能调不动WebSearch、Read、Write、Shell这些工具。写多了有安全风险写少了功能跑不起来。后面会给具体白名单写法。如果你还没装 QwenCode先去官网看安装说明。装完后在终端输入qwen --version确认版本。模型和 API Key 的配置也在settings.json里如果你用 TaoToken 这类兼容接口Base URL 和 Key 的填法后面会给示例。这一节先把整体骨架立起来settings.json开实验特性SKILL.md写技能逻辑allowedTools控权限。下一节讲前置准备和具体配置。2. TaoToken 前置准备与 settings.json 实验特性开启在写 Skill 之前得先把 QwenCode 的模型通道配通。QwenCode 本身支持多种模型接入方式如果你手头没有官方 Key或者想统一管理多个模型的调用可以用 TaoToken 的兼容接口。它的 API 地址是https://taotoken.net/api模型对话、Coding Plan、API Keys 管理都在控制台里。先确认 QwenCode 版本。打开终端qwen --version如果提示命令不存在说明没装好或者没加进 PATH。Win11 下重开一个终端试试或者检查安装时的路径提示。接下来打开settings.json。路径就是%USERPROFILE%\.qwen\settings.json。用记事本或 VS Code 打开都行。初始内容大概长这样{ model: { name: qwen-max, apiKey: 你的Key, baseUrl: https://taotoken.net/api } }如果你用 TaoToken 的 KeybaseUrl填https://taotoken.net/apiapiKey填你在控制台生成的 Key。模型名按你实际要用的填比如qwen-max、qwen-plus等。具体可用模型列表在模型对话页面能看到。然后开启 Skill 实验特性。在settings.json里加上{ model: { name: qwen-max, apiKey: 你的Key, baseUrl: https://taotoken.net/api }, experimental: { skills: true } }保存。注意 JSON 格式别写错多一个逗号少一个引号都会导致配置不生效。保存后重启终端里的qwen会话。这里有个容易忽略的点experimental.skills不开skills/文件夹里的SKILL.md不会被扫描。我一开始没加这个问天气 AI 直接走通用搜索完全没读我的技能文件。加上之后才触发。权限方面allowedTools是在SKILL.md的 frontmatter 里写的不是settings.json。但settings.json里可以配全局的工具开关。如果你发现某个工具死活调不起来先检查SKILL.md里的allowedTools有没有写对再检查settings.json有没有全局禁用。TaoToken 的 Key 获取在控制台的 API Keys 页面生成后复制粘贴到settings.json的apiKey字段。如果你要用 Coding Plan 做长期编码任务也可以在控制台看套餐说明。接入文档里有完整的 Base URL 和参数说明。配置改完后建议先用一次普通对话验证模型通道通不通。在终端输入qwen进入交互问一句“你好”能正常回复说明模型配置没问题。然后再去写 Skill。3. 可复制配置SKILL.md 模板与 allowedTools 白名单写法这一节给两个完整可复制的 Skill 模板天气助手和数据统计。重点看allowedTools的写法以及SKILL.md的 frontmatter 格式。先建文件夹。进入%USERPROFILE%\.qwen\skills\新建weather-advisor文件夹。在里面新建SKILL.md。文件内容--- name: weather-advisor description: 当用户询问天气、气温、穿衣建议或出门提醒时自动触发。 allowedTools: - WebSearch --- # 天气与穿衣助手 你是一个贴心且严谨的出行助手。当用户询问天气或准备出门时请严格按照以下逻辑执行 ## 1. 获取当前位置 首先用户没有指定位置的时候你需要确定用户的地理位置如果用户指定了位置就使用用户的地理位置。 - 如果无法自动获取用户位置请礼貌地询问用户所在的城市。 ## 2. 查询天气数据 获取城市后直接使用 web_search 工具搜索天气信息 - 搜索关键词示例城市名 今天天气 日期 或 城市名 明天天气 或 城市名 天气 中央气象台 - 推荐数据源优先从搜索结果中提取中央气象台nmc.cn、中国天气网等权威网站的数据。 - 提取信息温度范围最高/最低温、天气状况晴/雨/多云等、风向风力、降水概率。 ### 注意事项 - 如果第一次搜索结果不理想可尝试更换关键词如添加“中央气象台”或“中国天气网”。 - 搜索时可以带上具体日期以提高准确性例如“杭州 4月10日 天气”。 ## 3. 分析与建议 根据获取到的天气数据温度、天气状况、降水概率给出具体的建议 ### 穿衣建议 - 10°C寒冷。建议穿羽绒服、厚毛衣、戴围巾。 - 10°C - 20°C凉爽/舒适。建议穿风衣、夹克、薄卫衣。 - 20°C - 28°C温暖。建议穿长袖 T 恤、衬衫。 - 28°C炎热。建议穿短袖、短裤、裙子注意防晒。 ### 雨具建议 - 下雨/雪如果天气状况包含 Rain、Snow 或降水概率 30%强烈建议带伞。 - 多云/阴天如果是 Cloudy 且降水概率 10%可以不带伞但带一把折叠伞备用也无妨。 - 晴天如果是 Sunny建议带遮阳伞或涂抹防晒霜。 ## 4. 输出格式 请务必按照以下 Markdown 格式回复将“出门必带”放在最前面 ### 出门必带 - 手机确认已带好手机。 - 钥匙确认已带好钥匙家门/车钥匙。 ### 天气概况 - 位置[城市名] - 气温[温度] - 状况[描述] ### 贴心建议 - 穿衣[具体建议] - 雨具[是/否/建议]注意allowedTools里写的是WebSearch对应技能里调用的web_search工具。大小写和拼写要跟 QwenCode 的工具名一致。写错了工具调不起来AI 会报“没有权限”或者直接跳过。第二个模板数据统计。新建sample-stats文件夹里面放SKILL.md--- name: sample-stats description: 当用户需要分析借样Excel数据统计各部门的借样单数量、发货数量及金额时自动触发。 allowedTools: - Read - Write - Shell --- # 借样数据统计助手 你是一个专业的数据分析师。当用户提供借样Excel文件并要求统计时请按照以下步骤执行 ## 1. 读取Excel文件 首先确认用户提供的Excel文件路径。如果未提供请询问用户。使用 Python 的 pandas 库读取文件。 python import pandas as pd df pd.read_excel(用户提供的文件路径)2. 数据清洗与筛选根据需求我们需要排除“不需要归还”的数据。筛选条件排除掉“是否归还”列中包含“不归还”或“否”的行或者排除“借样状态”为“已完结-不归还”的行。 保留数据仅保留“是否归还”为“是”或“部分归还”以及“未归还”的有效借样数据。3. 数据分组统计根据“所属部门”列进行分组并计算以下指标借样单数量统计该部门下的行数即单据编号的数量。实际发货数量对“实际发货数量件”列求和。实际发货金额对“实际发货总额元”列求和。Python 处理逻辑示例stats df_filtered.groupby(所属部门).agg({ 单据编号: count, 实际发货数量件: sum, 实际发货总额元: sum }).rename(columns{单据编号: 借样单数量})4. 输出结果将统计结果保存为一个新的 Excel 文件或 CSV 文件并展示前几行给用户预览。输出文件名各部门借样统计汇总.xlsx展示格式使用 Markdown 表格展示结果包含列所属部门、借样单数量、实际发货数量、实际发货金额。额外信息告知用户文件已生成并提供下载/保存路径。这个模板里 allowedTools 写了 Read、Write、Shell。Read 用来读 ExcelWrite 用来写新文件Shell 用来跑 Python 脚本。如果你不想让 AI 执行 Shell 命令可以去掉 Shell但那样就得靠 AI 自己解析 Excel复杂表格容易出错。 allowedTools 白名单的写法就是 YAML 列表每行一个工具名前面加 -。常见工具名包括 WebSearch、Read、Write、Shell、Edit 等。具体支持哪些可以看 QwenCode 文档里的工具列表。写多了不会报错但权限过大有风险写少了功能受限。按技能实际需要写就行。 两个模板都保存后skills/ 目录结构是skills/ ├── weather-advisor/ │ └── SKILL.md └── sample-stats/ └── SKILL.md## 4. 验证请求一次实际调用确认 Skill 生效 配置写完得验证 Skill 到底有没有被触发。步骤很简单但有几个细节要注意。 先重启终端。在 skills 目录下打开 cmd输入 qwen 进入交互模式。然后输入今天天气怎么样如果 Skill 生效AI 会先问你在哪个城市或者直接根据你的位置搜索天气然后按 SKILL.md 里定义的格式输出包含“出门必带”“天气概况”“贴心建议”三个部分。如果没生效AI 会走通用搜索输出格式不固定也不会问你要不要带伞。 怎么判断是 Skill 触发了还是通用能力看输出格式。Skill 里的格式是强约束的出门必带 一定在最前面。通用能力不会这么规整。 如果没触发先检查 settings.json 里的 experimental.skills 是不是 true。然后检查 SKILL.md 的 description 是不是跟你的问法匹配。比如你问“今天天气怎么样”description 里写了“当用户询问天气、气温、穿衣建议或出门提醒时自动触发”这个匹配度就很高。如果你问“帮我查下气象”可能匹配不上因为 description 里没写“气象”这个词。 再验证数据统计 Skill。准备一个 Excel 文件比如 借样数据.xlsx放在某个目录下。在终端里输入帮我统计这个Excel里各部门的借样单数量和金额文件在 D:\data\借样数据.xlsx如果 Skill 生效AI 会调用 Read 读文件用 Shell 跑 Python 脚本然后生成 各部门借样统计汇总.xlsx并用 Markdown 表格展示前几行。你可以在输出里看到它执行了哪些步骤。 这里有个实测细节Shell 工具调用时AI 会生成 Python 代码并执行。如果你的环境里没装 pandas会报 ModuleNotFoundError。提前装好 bash pip install pandas openpyxlopenpyxl是读写 xlsx 的依赖不装的话pd.read_excel会报错。验证成功后你可以把常用 Skill 固定下来。比如每周一早上跑一次数据统计直接跟 QwenCode 说“统计借样数据”它就会按SKILL.md里的流程走。不用每次重复写提示词也不用改代码。如果想让 Skill 更精准可以在description里加更多触发词。比如天气 Skill 加上“气温”“穿衣”“出门”“下雨”“防晒”等词。数据统计 Skill 加上“借样”“发货”“部门统计”“Excel汇总”等词。匹配度越高触发越稳定。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配 Skill 过程中最容易卡在几个报错上。下面按真实遇到的顺序列出来。401 Unauthorized这个通常是settings.json里的apiKey不对或者baseUrl写错了。检查 Key 有没有复制完整有没有多余空格。如果用 TaoTokenbaseUrl应该是https://taotoken.net/api不要多加斜杠或者路径。改完后重启qwen会话。local proxy failed这个报错一般出现在网络请求发不出去的时候。检查你的网络环境是否能正常访问baseUrl。如果你用的是公司内网可能有防火墙限制。换一个网络环境试试。另外确认settings.json里没有配多余的代理参数。reading choices 相关报错这个通常出现在模型返回格式跟 QwenCode 预期不一致的时候。检查model.name是不是填了不支持的模型名。如果你用 TaoToken去模型对话页面确认可用模型列表填一个确定支持的。另外检查SKILL.md里的输出格式要求是不是太复杂导致模型返回结构混乱。简化一下格式约束试试。OAuth 相关报错如果你用的是需要 OAuth 的接入方式检查 token 有没有过期。TaoToken 的 API Key 方式不需要 OAuth直接填 Key 就行。如果你混用了两种认证方式清掉多余的配置字段。Skill 不触发这个不算报错但最常见。排查顺序experimental.skills是否为trueSKILL.md的 frontmatter 格式是否正确---开头结尾name和description必填description是否跟用户问法匹配allowedTools里的工具名是否拼写正确。我踩过的坑是allowedTools写了websearch小写实际应该是WebSearch导致工具调不起来AI 直接说“我没有搜索权限”。工具调用失败如果 AI 说“我无法读取文件”或者“我没有执行命令的权限”检查allowedTools里有没有加对应的工具。读文件要Read写文件要Write跑命令要Shell搜索要WebSearch。少一个都会导致对应操作失败。JSON 格式错误settings.json改完后如果qwen启动报配置解析错误用 JSON 校验工具检查一下。常见问题是多了一个逗号、少了一个引号、括号不匹配。VS Code 里打开会有红色波浪线提示。SKILL.md 里的代码块嵌套问题SKILL.md本身是 Markdown里面如果嵌了 Python 代码块注意最外层的---frontmatter 和代码块的 不要冲突。我遇到过在 frontmatter 后面直接写代码块导致解析出错。frontmatter 结束后空一行再写正文。排障基本就这些。核心原则先确认模型通道通再确认 Skill 开关开再确认description匹配最后确认allowedTools权限够。一层层往下查大部分问题都能定位。6. 从天气到数据统计把 Skill 用成日常效率工具天气 Skill 只是入门 demo真正省时间的是那些重复性工作。比如每周要从 ERP 导出借样数据按部门统计单量、发货数量、金额再汇总成新 Excel 发给领导。以前手动做要半小时现在写一次SKILL.md以后每次把文件路径丢给 QwenCode 就行。关键是把SKILL.md写细。数据统计那个模板里筛选条件、分组字段、输出格式都写死了。AI 每次执行都按这个来不会今天按部门分、明天按产品分。稳定性来自约束不是来自 AI 的“智能”。如果你想让 Skill 更通用可以把文件路径做成参数。比如在SKILL.md里写“询问用户文件路径”而不是写死一个路径。这样同一个 Skill 可以处理不同月份、不同部门的文件。allowedTools的白名单也要按需调整。天气 Skill 只需要WebSearch数据统计需要Read、Write、Shell。不要图省事全加上权限越大AI 误操作的风险越高。比如你不想让 AI 删文件就别加Shell里的删除权限如果 QwenCode 支持细粒度控制的话。长期用下来建议把常用 Skill 分类管理。skills/下按业务建文件夹比如skills/weather/、skills/data-stats/、skills/file-organize/。每个文件夹里一个SKILL.md。description写清楚触发场景避免多个 Skill 抢同一个问题。如果你需要更稳定的模型通道来跑这些 SkillTaoToken 的 Coding Plan 适合长期编码和 Agent 类任务API Keys 页面可以管理多个 Key。接入文档里有完整的 Base URL 和参数说明。模型对话页面可以快速验证模型是否可用。最后一步把你最常做的重复工作写成一个SKILL.md跑一次验证然后固定下来。下次直接说需求让 AI 按你的规矩干活。