1. 从 SKILL.md 到飞书 CLIAgent Skills 落地时最容易卡在哪AI Agent Skills 这套东西本质上是给 Agent 写一份「说明书 工具箱」让它知道某个能力是什么、什么时候用、怎么调、出错怎么办。SKILL.md 负责定义飞书 CLI 负责执行两者之间靠一条稳定的模型调用通道串起来。如果你正在做多工具协作的 Agent大概率会遇到三个卡点SKILL.md 写得太像人类文档Agent 解析不了飞书 CLI 的鉴权散落在各个脚本里换台机器就崩模型 Key 和 CLI 凭据混在一起排查问题时根本分不清是哪一层挂了。这篇就按「定义 → 配置 → 调用 → 验证 → 排障」的顺序走一遍。适合已经写过一两个 Skill、但还没把链路跑顺的开发者。核心思路是SKILL.md 用结构化 frontmatter 声明依赖和权限飞书 CLI 用统一入口执行模型调用统一走 TaoToken 的 Key这样任何一层出问题都能快速定位。下面给的都是可以直接复制改参数用的片段不是概念演示。2. TaoToken 前置统一 Key 通道怎么接TaoToken 在这里扮演的角色是「模型调用的统一入口」。你的 Agent 在触发 Skill 时往往需要先让模型理解用户意图、生成 CLI 参数这一步的模型请求就走 TaoToken。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。接入前先确认两件事一是你已经在控制台创建了 API Key二是本地环境能正常访问 API 基址。Key 的创建入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制保存后面配置里会用到。如果你还没决定用哪个模型可以先在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下调用是否通确认通道没问题再写进 Skill。配置方式推荐用环境变量不要硬编码进 SKILL.md 或脚本。原因很简单SKILL.md 是要提交到仓库、可能被 Agent 反复读取的Key 写进去等于泄露。环境变量方案如下export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 OpenAI 兼容的 SDK直接把 base_url 指向 TaoToken 的 API 地址即可。Python 里大概是这样import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: 把这句话转成飞书 CLI 发送命令的参数}], ) print(resp.choices[0].message.content)跑通这一步说明模型通道是活的。接下来才是把它和 SKILL.md、飞书 CLI 串起来。3. 可复制配置SKILL.md 骨架 飞书 CLI 调用3.1 SKILL.md 骨架SKILL.md 的关键是 frontmatter 要机器可读正文要人机都能看懂。下面这个骨架可以直接拿去改--- name: feishu-notify version: 1.0.0 description: 飞书消息通知技能向指定群聊发送文本或 Markdown 消息。当用户需要发送通知、回传执行结果、推送告警时使用。 metadata: requires: bins: [lark-cli] cliHelp: lark-cli im --help env: - TAOTOKEN_API_KEY - TAOTOKEN_BASE_URL --- # feishu-notify (v1) **CRITICAL — 执行前必须先确认 lark-cli 已登录且 TAOTOKEN_API_KEY 已设置。** ## Core Concepts - **chat_id**群聊唯一标识以 oc_ 开头。 - **message_id**消息唯一标识以 om_ 开头。 - **identity**--as user 用用户身份--as bot 用机器人身份。 ## Shortcuts | Shortcut | 说明 | 身份 | 风险 | |----------|------|------|------| | messages-send | 发送消息 | user/bot | write | ## Examples ### 发送文本消息 bash lark-cli im messages-send \ --chat-id oc_xxxxxxxxxxxx \ --text Skill 执行完成发送 Markdown 消息lark-cli im messages-send \ --chat-id oc_xxxxxxxxxxxx \ --markdown ## 执行结果\n\n- 状态成功\n- 耗时1.2sTroubleshooting问题 1权限不足错误码 99991679说明缺少im:message:send_as_botscope。lark-cli auth login --scope im:message:send_as_bot注意 frontmatter 里的 env 字段这是告诉 Agent「这个 Skill 依赖哪些环境变量」。很多 Skill 写崩就是因为没声明依赖Agent 跑到一半发现 Key 不存在。 ### 3.2 飞书 CLI 调用封装 飞书 CLI 本身命令不复杂但如果你要在 Agent 里反复调用建议包一层 Python 函数把错误处理和重试统一掉 python import subprocess import json def send_feishu_message(chat_id: str, text: str None, markdown: str None) - dict: cmd [lark-cli, im, messages-send, --chat-id, chat_id] if text: cmd [--text, text] if markdown: cmd [--markdown, markdown] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise RuntimeError(f飞书 CLI 调用失败: {result.stderr}) return json.loads(result.stdout)调用时resp send_feishu_message( chat_idoc_xxxxxxxxxxxx, markdown## Skill 触发成功\n\n模型通道正常飞书回传正常。 ) print(resp[data][message_id])这里有个细节--markdown参数里的换行要用\n不要直接敲回车否则 shell 解析会出问题。我试过在脚本里直接写多行字符串结果 CLI 只收到了第一行。4. 验证请求本地跑通一次 Skill 触发与飞书回传验证分三步缺一不可。第一步确认模型通道。用前面的 Python 片段发一条请求看是否返回内容。如果报 401说明 Key 不对如果报连接超时检查 base_url 是否写成了带 UTM 的地址API 地址不带 UTM。第二步确认飞书 CLI 鉴权。执行lark-cli auth status期望输出里authenticated为true且 scopes 里包含im:message:send_as_bot。如果没有补授权lark-cli auth login --scope im:message:send_as_bot第三步端到端跑一次。写一个最小脚本让模型生成一句通知文案再通过飞书 CLI 发出去import os from openai import OpenAI from feishu_utils import send_feishu_message # 上面的封装函数 client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: 生成一句 20 字以内的任务完成通知}], ) text resp.choices[0].message.content.strip() result send_feishu_message(chat_idoc_xxxxxxxxxxxx, texttext) print(消息已发送:, result[data][message_id])如果飞书群里收到了这条消息说明「模型通道 → Skill 逻辑 → 飞书 CLI」整条链路是通的。这一步跑通之后再把逻辑塞进 SKILL.md 描述的流程里Agent 就能自动执行了。5. 本篇常见错排查5.1 模型请求 401 或 403先检查TAOTOKEN_API_KEY是否设置、是否有多余空格。再确认 base_url 是https://taotoken.net/api不要带任何查询参数。如果 Key 是在控制台刚创建的确认没有复制错行。5.2 飞书 CLI 报 99991679这是权限不足的典型错误码。解决方式是补 scopelark-cli auth login --scope im:message:send_as_bot补完后再跑一次lark-cli auth status确认 scope 已生效。注意 scope 是累加的补授权不会覆盖已有权限。5.3 SKILL.md 被 Agent 忽略常见原因是 frontmatter 格式错误。YAML 对缩进敏感metadata下的requires和env必须对齐。可以用下面命令快速校验python -c import yaml; yaml.safe_load(open(SKILL.md).read().split(---)[1])如果没有报错说明 YAML 语法没问题。如果 Agent 还是忽略检查 SKILL.md 是否放在 Agent 扫描的目录下。5.4 消息发送成功但群里看不到先确认chat_id是否正确必须以oc_开头。再确认机器人是否在目标群里用 bot 身份发送时机器人必须已在群内。如果用的是 user 身份确认当前登录用户有发消息权限。5.5 环境变量在 Agent 运行时丢失Agent 可能以子进程方式执行 Skill父进程的环境变量不一定继承。稳妥做法是在 Skill 启动脚本里显式加载set -a source .env set a.env文件里放TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL不要提交到仓库。6. 把链路固定下来长期编码与 Agent 场景的 Key 管理单次跑通不难难的是长期稳定。如果你要把这套 Skill 用在日常编码或 Agent 自动化里建议把模型调用统一收敛到 TaoToken 的 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。这样 Key 管理、额度查看、模型切换都在一个地方不用每个 Skill 单独配。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果你用的是 Claude Code 这类工具Anthropic 兼容配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。最后给一个实用建议把 SKILL.md 里的env声明和实际环境变量做一次自动比对写进 CI。这样每次改 Skill 都不会漏配依赖。链路稳定之后Agent 触发 Skill、飞书回传结果就是一条可预期的流水线排查问题也只需要看是模型层、Skill 层还是 CLI 层。