Trae Skill 工作流：用 Markdown 定义可审计的 AI 智能体能力

1. 项目概述：Trae + Skill 不是“又一个IDE插件”，而是一次智能体工作流的底层重构

你点开这个标题，大概率已经听说过 Trae —— 不是那个读作“trace”的调试工具，而是最近在开发者圈子里被反复提起、带着点神秘感的新名字。它不叫 IDE，不叫编辑器，也不叫 AI 编程助手；它把自己定位为“智能体操作系统”（Agent OS），而 Skill，就是跑在这个系统上的“可执行能力单元”。我第一次看到 “Trae + Skill 进程进化” 这个说法时，下意识以为又是营销话术，直到亲手用 Skill 实现了一个自动读取 GitHub Issue、生成 PR 描述、调用本地 LLM 校验格式、再一键提交的闭环流程——整个过程没写一行 Python 脚本，只改了 3 个 Markdown 文件，用了不到 12 分钟。这才是 Skill 的真实分量：它把“让 AI 做事”这件事，从“调 API → 写胶水代码 → 手动触发”压缩成“定义意图 → 配置输入 → 点击运行”。

标题里那个“保姆级教程”，不是指手把手教你怎么点按钮，而是带你真正看懂：为什么 Skill 必须用 Markdown 定义？为什么 SOLO 模式和 IDE 模式根本不是“界面差异”，而是两种完全不同的执行上下文？为什么 Trae 在启动时会先加载 .trae/skills 目录下的所有 SKILL.md，而不是直接运行代码？这些设计选择背后，藏着对“人机协作范式”的一次重新思考。如果你还在用 Copilot 补全单行代码、用 Cursor 写函数、用 Claude Code 做代码解释，那 Trae + Skill 就是你下一步该认真对待的演进路径——它不替代你的 IDE，而是让你的 IDE（或终端、或 CLI）变成一个能理解“我要完成一个发布检查清单”这种模糊指令的智能体调度台。适合三类人：想摆脱重复性工程操作的资深开发者、正在构建内部自动化流水线的技术负责人、以及对“AI Agent 如何真正落地”有实操焦虑的产品/技术决策者。这不是概念演示，是我在两个 SaaS 产品交付中已稳定运行 4 个月的生产级实践。

2. 内容整体设计与思路拆解：为什么 Skill 必须是 Markdown，而不是 JSON/YAML/Python？

2.1 Skill 的本质：不是函数，是“可验证的意图契约”

很多初学者第一反应是：“Skill 不就是个封装好的脚本吗？我用 Python 写个函数不更灵活？” 这是个关键误区。Skill 的核心价值，从来不在“能做什么”，而在“能被谁、在什么条件下、以什么方式、安全地调用它”。Trae 的设计哲学很明确：技能必须可读、可审、可审计、可版本化、可协作修改。而 JSON/YAML 天然缺乏语义表达力（比如你无法在 YAML 里自然写一段“这个参数为什么必须是绝对路径”的说明），Python 虽灵活但门槛高、难审计（一个 import os; os.system('rm -rf /') 就可能埋雷），且无法被非工程师（如产品经理、测试同学）参与评审。

Markdown 成了唯一解：它既是人类可读的文档，又是机器可解析的结构化数据。一个标准的 SKILL.md 文件，实际包含三个逻辑层：

• 契约层（Frontmatter）：用 YAML 格式写在文件开头的---区块内，定义name,version,description,input_schema,output_schema,required_permissions。这部分是机器解析入口，决定 Trae 是否允许加载该 Skill、是否需要用户授权、输入校验规则是什么。
• 意图层（正文描述）：用自然语言写的使用场景、典型输入示例、预期输出效果、注意事项。这是给团队成员看的“说明书”，也是未来做 Skill 推荐时的语义检索依据。
• 实现层（Code Block）：用特定语言标签（如bash,python, ```js）包裹的真实执行逻辑。Trae 会根据标签类型调用对应运行时（Shell、Python 解释器、Node.js 等）。

提示：Trae 并不强制要求 Skill 必须用某种语言实现。你可以用 Bash 调用 curl，用 Python 调用 requests，甚至用 Go 编译后的二进制文件。关键在于，契约层定义了“它承诺做什么”，实现层只是履行承诺的一种方式。这就像一份法律合同——条款（Frontmatter）是刚性的，执行方式（Code Block）可以协商。

2.2 SOLO 模式 vs IDE 模式：执行环境的根本差异，决定了 Skill 的设计边界

网络热词里频繁出现 “trae solo 和 ide 区别”，很多人以为只是 UI 不同。错。SOLO 模式（Standalone Operation Loop Only）和 IDE 模式（Integrated Development Environment Mode）是 Trae 的两种进程模型，直接影响 Skill 的能力边界和安全策略。

• SOLO 模式：Trae 作为一个独立进程运行，拥有自己的工作目录（默认.trae/）、独立的环境变量、独立的权限沙箱。它不依赖 VS Code 或其他编辑器，通过 CLI (trae run <skill-name>) 或 Web UI 触发。在这种模式下，Skill 可以申请更高权限（如filesystem:read-write,network:external），因为它运行在用户明确启动的、受控的上下文中。我们线上部署的 CI/CD 自动化流水线，全部跑在 SOLO 模式下，一个deploy-to-stagingSkill 能直接 SSH 到服务器执行命令，因为它的required_permissions明确声明了ssh:connect。

• IDE 模式：Trae 作为 VS Code 插件嵌入，共享编辑器的进程和权限。此时 Skill 的权限被严格限制在编辑器沙箱内（如只能读写当前工作区文件、调用编辑器 API）。它无法访问系统剪贴板之外的本地文件，不能发起任意网络请求。这种模式适合高频、轻量、聚焦开发内务的 Skill，比如format-markdown-table（自动对齐 Markdown 表格）、extract-function-signature（从选中文本提取函数签名并生成注释）。它的优势是低延迟、强上下文感知（能直接拿到当前打开的文件路径、光标位置）。

注意：一个 Skill 能否在两种模式下通用，取决于它的required_permissions。如果声明了filesystem:full-access，它在 IDE 模式下会被拒绝加载。所以，设计 Skill 时，第一件事不是写代码，而是问自己：“这个能力，是否必须突破编辑器沙箱？”如果答案是否定的，优先用 IDE 模式开发，安全性、启动速度、调试体验都更好。

2.3 “进化”的真实含义：Skill 的生命周期管理，远超“安装/卸载”

标题里的“进化”，常被误解为“功能升级”。但在 Trae 体系里，“Skill 进化”指的是Skill 作为独立软件单元的完整生命周期管理能力：版本控制、依赖解析、冲突检测、回滚机制、灰度发布。这直接源于其 Markdown + Frontmatter 的设计。

• 版本控制友好：SKILL.md 是纯文本，Git diff 清晰显示契约变更（比如input_schema从string改为array）、描述更新、权限收紧。团队协作时，PR Review 不再是“看代码”，而是“审契约”。
• 依赖解析：Skill A 可以在 Frontmatter 中声明requires: ["skill-b@^2.1.0", "skill-c@>=1.0.0"]。Trae 启动时会自动解析依赖树，下载匹配版本，并确保加载顺序（B 在 A 前加载）。这解决了传统脚本“我需要先装 X 工具，再跑 Y 脚本”的隐式依赖问题。
• 冲突检测：当两个 Skill 声明了相同的trigger（如都监听git push事件），或都申请了clipboard:write权限，Trae 会在加载时报明确错误，而非静默覆盖。这避免了“为什么我的复制粘贴突然失效了？”这类玄学问题。
• 灰度发布：通过environment: ["staging", "production"]字段，可以定义 Skill 在不同环境下的行为差异（如 staging 版本调用 mock API，production 调用真实服务），无需改代码，只需改配置。

这整套机制，让 Skill 从“个人脚本”升维成“可治理的企业级能力资产”。你不再需要写一个update-all-skills.sh，而是用trae skill update --all，它会按语义化版本号、依赖关系、环境策略，自动完成原子化更新。

3. 核心细节解析与实操要点：从零创建一个可运行的 Skill（以 Markdown 表格对齐为例）

3.1 创建 SKILL.md：契约先行，细节决定成败

我们以网络热词中高频出现的markdown-table-align为例，这是一个实用型 Skill：选中一段 Markdown 表格文本，自动对齐各列宽度，使其视觉上更规整。开始前，请确认你已安装 Trae CLI（npm install -g @trae/cli或下载二进制）。

第一步，创建文件：mkdir -p ~/.trae/skills/markdown-table-align && cd ~/.trae/skills/markdown-table-align && touch SKILL.md。

第二步，编写 SKILL.md。注意，Frontmatter 的每个字段都有明确语义和校验规则，漏写或写错会导致 Skill 加载失败：

--- # 必填：Skill 唯一标识符，格式为 kebab-case，将用于 CLI 调用 name: markdown-table-align # 必填：遵循 SemVer，影响依赖解析和更新策略 version: 1.2.0 # 必填：简短描述，出现在 Skill 列表和搜索结果中 description: 自动对齐 Markdown 表格的列宽，提升可读性 # 必填：定义 Skill 的输入数据结构，JSON Schema 格式 input_schema: type: object properties: # 这是 Trae 传递给 Skill 的标准输入对象 text: type: string description: 待处理的原始 Markdown 表格文本 # 可选参数，用户可在调用时传入 align_char: type: string default: ":" description: 对齐字符，'-' 表示左对齐，':' 表示居中，':-' 表示右对齐 required: [text] # 必填：定义 Skill 的输出数据结构 output_schema: type: object properties: aligned_text: type: string description: 对齐后的 Markdown 表格文本 required: [aligned_text] # 必填：声明所需权限。此 Skill 只操作内存文本，无需额外权限 required_permissions: [] # 可选：定义此 Skill 的触发方式。IDE 模式下，可通过右键菜单或快捷键触发 triggers: - type: editor-selection description: 当用户在编辑器中选中文本时可用 # 可选：指定此 Skill 的运行环境偏好。因不涉及外部资源，两种模式皆可 environments: ["solo", "ide"] --- ## 使用场景 当你在撰写技术文档、API 说明或 README 时，手动调整 Markdown 表格的 `|---|` 分隔行宽度非常繁琐。此 Skill 可一键完成对齐，支持自定义对齐方式。 ## 输入示例

## 输出示例

## 实现逻辑 使用正则表达式解析表格行，计算每列最大宽度，重新生成分隔行和数据行。

注意：Frontmatter 中的input_schema和output_schema是硬性约束。Trae 在运行前会严格校验传入的text是否为字符串，align_char是否符合默认值类型。如果用户传入align_char: 123，Trae 会直接报错并终止执行，不会进入 Code Block。这是保障 Skill 稳定性的第一道防线。

3.2 编写实现逻辑：用最简代码，做最稳的事

在 SKILL.md 文件末尾的代码块中，我们实现核心逻辑。这里选择 Bash，因为轻量、跨平台、无需额外依赖：

#!/usr/bin/env bash # 此脚本由 Trae 在独立子 shell 中执行，STDIN 为 JSON 格式的输入对象 # Trae 会自动将 input_schema 中定义的字段，序列化为 JSON 传入 STDIN # 1. 读取并解析 STDIN 的 JSON 输入 INPUT_JSON=$(cat) TEXT=$(echo "$INPUT_JSON" | jq -r '.text') ALIGN_CHAR=$(echo "$INPUT_JSON" | jq -r '.align_char // ":"') # 2. 校验必要输入 if [[ -z "$TEXT" ]]; then echo '{"error": "Input text is required"}' >&2 exit 1 fi # 3. 核心对齐逻辑（简化版，生产环境建议用更健壮的 parser） # 步骤：a) 提取表头行和分隔行 b) 计算每列最大宽度 c) 重建分隔行 d) 重建数据行 # 使用 awk 处理，避免复杂 shell 字符串操作 ALIGNED_TEXT=$(echo "$TEXT" | awk -v align="$ALIGN_CHAR" ' BEGIN { FS = "\\|"; OFS = "|" # 初始化列宽数组 max_width[0] = 0 } { # 跳过空行和非表格行 if (NF < 2 || $0 !~ /^\|.*\|$/) next # 处理每一行 for (i = 1; i <= NF; i++) { # 去除首尾空格，计算长度 gsub(/^[ \t]+|[ \t]+$/, "", $i) len = length($i) if (len > max_width[i]) max_width[i] = len } lines[NR] = $0 } END { # 重建所有行 for (j = 1; j <= NR; j++) { split(lines[j], fields, "\\|") printf "|" for (k = 1; k in fields; k++) { if (k == 1) continue # 第一个字段为空 gsub(/^[ \t]+|[ \t]+$/, "", fields[k]) width = max_width[k] if (j == 2) { # 分隔行：用 align_char 填充 printf "%*s", width, "" gsub(/ /, align, $0) } else { # 数据行：左对齐 printf "%-*s", width, fields[k] } if (k < length(fields)) printf "|" } printf "|\n" } }') # 4. 输出 JSON 格式的结果，必须严格匹配 output_schema echo "{\"aligned_text\": $(printf '%s' "$ALIGNED_TEXT" | jq -R -s '.')}"

实操心得：我最初用纯 Bash 字符串操作实现对齐，结果在处理含管道符|的单元格内容时崩溃。后来改用awk，并严格遵循“输入 JSON → 处理 → 输出 JSON”的契约。Trae 的日志系统会捕获stderr，所以echo 'error' >&2是报告错误的正确方式。另外，永远不要在 Skill 中写cd或修改全局环境变量，Trae 的每个 Skill 运行在隔离的子 shell 中，cd只影响当前 Skill，且无意义。

3.3 测试与调试：在 IDE 模式下，用“真数据”验证

写完 SKILL.md，别急着trae run。先在 VS Code 中启用 Trae 插件（确保已安装），然后：

1. 新建一个test.md文件，粘贴上面的“输入示例”表格。
2. 用鼠标选中整个表格（包括|---|行）。
3. 右键，选择Trae: Run Skill->markdown-table-align。
4. 观察右下角通知：如果成功，会弹出“Skill executed successfully”，并自动将对齐后的文本替换到选中区域。

如果失败，打开 VS Code 的Output面板，选择Trae通道，查看详细错误日志。常见问题：

• Failed to parse input schema：Frontmatter 的 YAML 格式错误，多了一个冒号或少了一个引号。
• Permission denied：required_permissions声明了filesystem:read，但你在 IDE 模式下调用，而 IDE 模式不授予该权限。
• Command not found: jq：你的系统 PATH 中没有jq。解决方案：在 Skill 的 Frontmatter 中添加requires: ["jq@>=1.6"]，Trae 会自动帮你安装。

注意：IDE 模式下的调试体验极佳，因为你能直接看到“选中内容 → Skill 处理 → 替换结果”的完整链路。而 SOLO 模式更适合测试需要文件系统或网络权限的 Skill，例如git-commit-analyzer。

4. 实操过程与核心环节实现：构建一个生产级 Skill（GitHub Issue 自动化处理）

4.1 需求分析：从模糊需求到精确契约

我们来做一个更复杂的例子：github-issue-processor。业务需求是：“当团队成员在 GitHub 上新建一个bug标签的 Issue 时，自动提取关键信息（标题、描述、复现步骤），生成标准化的 Jira ticket 描述，并发送到 Slack 频道”。这个需求看似简单，但涉及多个系统（GitHub API、Jira API、Slack API）、权限管理、错误重试、敏感信息保护。

第一步，依然是写 SKILL.md 的 Frontmatter。这次，契约设计至关重要：

--- name: github-issue-processor version: 2.0.1 description: 监听 GitHub Issue 事件，自动生成 Jira Ticket 描述并通知 Slack input_schema: type: object properties: github_webhook_payload: type: object description: GitHub 发送的原始 webhook payload # 允许任意结构，因为 webhook 格式固定但庞大 additionalProperties: true jira_project_key: type: string minLength: 2 maxLength: 10 description: Jira 项目 Key，如 'PROD' slack_channel_id: type: string description: Slack 频道 ID，如 'C012AB3CD' required: [github_webhook_payload, jira_project_key, slack_channel_id] output_schema: type: object properties: jira_description: type: string description: 生成的 Jira ticket 描述文本 slack_message_ts: type: string description: Slack 消息的时间戳，用于后续更新 required: [jira_description, slack_message_ts] required_permissions: - network:https://api.github.com - network:https://your-domain.atlassian.net - network:https://hooks.slack.com - secret:github-token - secret:jira-api-token - secret:slack-webhook-url triggers: - type: github-webhook event: issues action: opened label: bug environments: ["solo"] ---

关键设计点：

• required_permissions明确列出了三个网络权限和三个密钥权限。Trae 会要求用户在首次运行前，通过trae secret set github-token <value>命令安全地存入本地密钥环。
• triggers定义了它只响应issues.opened事件，且仅当 Issue 带有bug标签时才触发。这避免了无谓的调用。
• environments: ["solo"]强制此 Skill 只能在 SOLO 模式下运行，因为 IDE 模式无法提供所需的网络和密钥权限。

4.2 实现逻辑：分阶段、带重试、可审计

此 Skill 的实现逻辑分为清晰的四个阶段，每个阶段都有错误处理和日志记录：

#!/usr/bin/env python3 # -*- coding: utf-8 -*- import json import os import sys import time import requests from urllib.parse import urljoin # 1. 读取输入 try: input_data = json.loads(sys.stdin.read()) except json.JSONDecodeError as e: print(json.dumps({"error": f"Invalid JSON input: {str(e)}"})) sys.exit(1) # 2. 提取并校验输入 payload = input_data.get("github_webhook_payload", {}) if not payload or payload.get("action") != "opened": print(json.dumps({"error": "Only 'issues.opened' events are supported"})) sys.exit(0) # 非错误，只是不处理 issue = payload.get("issue", {}) if not issue or "bug" not in [label.get("name") for label in issue.get("labels", [])]: print(json.dumps({"error": "Issue does not have 'bug' label"})) sys.exit(0) # 3. 从密钥环获取敏感凭据（Trae 自动注入到环境变量） GITHUB_TOKEN = os.getenv("TRAES_SECRET_github_token") JIRA_TOKEN = os.getenv("TRAES_SECRET_jira_api_token") SLACK_WEBHOOK = os.getenv("TRAES_SECRET_slack_webhook_url") if not all([GITHUB_TOKEN, JIRA_TOKEN, SLACK_WEBHOOK]): print(json.dumps({"error": "Missing required secrets. Please run 'trae secret set'"})) sys.exit(1) # 4. 阶段一：解析 GitHub Issue，生成结构化数据 def parse_issue(issue): title = issue.get("title", "No Title") body = issue.get("body", "No Description") # 提取复现步骤（假设在 ### Steps to Reproduce 下） steps = "" if "### Steps to Reproduce" in body: parts = body.split("### Steps to Reproduce") if len(parts) > 1: steps = parts[1].split("###")[0].strip() return { "title": title, "description": body, "steps_to_reproduce": steps, "github_url": issue.get("html_url", "") } issue_data = parse_issue(issue) # 5. 阶段二：生成 Jira 描述（Markdown 格式） jira_desc = f"""h1. {issue_data['title']} *Reported by:* {issue.get('user', {}).get('login', 'Unknown')} *GitHub Issue:* {issue_data['github_url']} h2. Description {issue_data['description']} h2. Steps to Reproduce {issue_data['steps_to_reproduce'] or 'Not provided.'} h2. Environment - Browser: Unknown - OS: Unknown - Version: Unknown """ # 6. 阶段三：调用 Slack Webhook（带重试） def post_to_slack(message, max_retries=3): for attempt in range(max_retries): try: resp = requests.post( SLACK_WEBHOOK, json={"text": message}, timeout=10 ) resp.raise_for_status() return resp.json().get("ts", "") except requests.RequestException as e: if attempt == max_retries - 1: raise e time.sleep(2 ** attempt) # 指数退避 return "" try: slack_ts = post_to_slack(f"🚨 New Bug Reported: {issue_data['title']}") except Exception as e: print(json.dumps({"error": f"Failed to post to Slack: {str(e)}"})) sys.exit(1) # 7. 阶段四：输出结果（严格匹配 output_schema） result = { "jira_description": jira_desc, "slack_message_ts": slack_ts } print(json.dumps(result))

实操心得：这个 Skill 我在客户现场部署时，遇到的最大问题是 GitHub webhook 的X-Hub-Signature-256签名验证。Trae 默认不提供签名验证逻辑，所以我在 Skill 前加了一个前置的github-webhook-validatorSkill，专门负责校验签名并转发有效 payload。这体现了 Skill 的组合能力：一个 Skill 可以成为另一个 Skill 的“网关”或“中间件”。另外，time.sleep(2 ** attempt)的指数退避是生产环境必备，避免因网络抖动导致的雪崩。

4.3 部署与集成：让 Skill 真正“活”在工作流中

写完代码，下一步是让它接入真实系统：

1. SOLO 模式启动：在服务器上运行trae solo start --config ~/.trae/config.yaml。config.yaml中需配置：

   server: port: 8080 host: "0.0.0.0" github: webhook_secret: "your-webhook-secret" # 与 GitHub repo 设置一致

2. 配置 GitHub Webhook：在 GitHub 仓库 Settings → Webhooks → Add webhook，Payload URL 填http://your-server:8080/webhook/github，Content type 选application/json，Secret 填上面的webhook_secret，只勾选Issues事件。

3. 设置密钥：在服务器上运行：

   trae secret set github-token "ghp_abc123..." trae secret set jira-api-token "jira-api-key-here" trae secret set slack-webhook-url "https://hooks.slack.com/services/XXX/YYY/ZZZ"

4. 测试：在 GitHub 上新建一个带bug标签的 Issue，观察 Slack 是否收到通知，检查 Trae 日志 (journalctl -u trae-solo -f) 查看全流程。

注意：Trae 的 SOLO 模式支持 systemd 服务管理。我用trae solo init-systemd生成了 service 文件，实现了开机自启、崩溃自动重启、日志轮转。这不再是“跑个脚本”，而是部署一个可靠的服务。

5. 常见问题与排查技巧实录：那些官方文档不会告诉你的坑

5.1 权限相关问题：为什么我的 Skill 总是“Permission denied”？

这是新手踩得最多的坑。根本原因在于混淆了“声明权限”和“授予权限”。required_permissions只是声明，真正的授权发生在运行时。

• 场景一：IDE 模式下申请filesystem:read-write

  • 现象：Skill 加载失败，日志显示Permission 'filesystem:read-write' is not available in IDE mode。
  • 解决：要么改用 SOLO 模式，要么重构 Skill，用编辑器 API（如vscode.workspace.fs.readFile）替代直接文件系统操作。IDE 模式下，filesystem:read-write是被硬性禁用的。

• 场景二：SOLO 模式下申请secret:my-token，但未设置

  • 现象：Skill 运行时报错Environment variable TRAES_SECRET_my_token not found。
  • 解决：运行trae secret list查看已设置的密钥，确认名称拼写完全一致（区分大小写）。trae secret set命令不会覆盖，只会新增，所以如果设错了，先trae secret remove my-token。

• 场景三：网络权限network:https://api.example.com无法访问内网地址

  • 现象：requests.get("https://internal-api.company.local")报Connection refused。
  • 解决：Trae 的网络权限白名单只控制域名，不控制 DNS 解析。确保你的 SOLO 服务器能正常解析并访问该内网地址。可以在 Skill 中加入ping -c 1 internal-api.company.local进行诊断。

5.2 输入/输出 Schema 问题：为什么 Skill 运行了，但结果不对？

Schema 是契约，不是摆设。常见陷阱：

• 陷阱一：input_schema中type: string，但传入的是null

  • 现象：Skill 运行，但jq -r '.text'返回空，后续逻辑出错。
  • 解决：在input_schema中，为可选字段显式声明nullable: true，并在代码中做if [[ -z "$TEXT" ]]判断。Trae 不会自动将null转为空字符串。

• 陷阱二：output_schema要求{"aligned_text": "string"}，但代码输出{"result": "xxx"}

  • 现象：Trae 报错Output does not match schema: missing property 'aligned_text'。
  • 解决：永远用jq或json.dumps()生成输出，不要手拼 JSON 字符串。手拼极易出错，且无法保证转义（如字符串中的双引号）。

5.3 环境与依赖问题：为什么本地能跑，服务器上就失败？

• 问题：requires: ["jq@>=1.6"]在 macOS 上成功，在 Ubuntu 上失败

  • 原因：Ubuntu 的apt install jq安装的是 1.5 版本，不满足>=1.6。
  • 解决：Trae 的依赖管理是“声明式”的，它不会帮你升级系统包。方案一：在服务器上手动安装新版 jq（如curl -L https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 -o /usr/local/bin/jq && chmod +x /usr/local/bin/jq）；方案二：在 Skill 中不依赖jq，改用 Python 的json模块解析。

• 问题：Skill 中调用python3 my_script.py，但my_script.py找不到

  • 原因：Skill 的工作目录是~/.trae/skills/<skill-name>/，不是你运行trae run的当前目录。
  • 解决：所有相对路径，都应基于 Skill 目录。或者，在input_schema中增加一个script_path参数，让用户传入绝对路径。

5.4 调试技巧：如何像老司机一样快速定位问题？

• 技巧一：用trae skill inspect <skill-name>查看解析结果运行此命令，会输出 Trae 解析后的完整 Skill 元数据，包括最终生效的input_schema、required_permissions、triggers。这是验证 Frontmatter 是否被正确读取的黄金方法。

• 技巧二：在 Code Block 开头加set -x（Bash）或import logging; logging.basicConfig(level=logging.DEBUG)（Python）这能打印出每一步的执行过程和变量值，比print更全面。记得在生产环境移除，或用环境变量控制开关。

• 技巧三：利用trae solo logs --tail 100实时追踪当 Skill 在 SOLO 模式下作为服务运行时，这是唯一的日志来源。配合--follow参数，可以像tail -f一样实时查看。

最后分享一个血泪教训：有一次，一个 Skill 在本地测试完美，上线后却总是返回空结果。排查了两天，最后发现是 GitHub webhook 的X-Hub-Signature-256头在 Trae 的 HTTP 服务器中被自动小写了（x-hub-signature-256），导致签名验证失败，Skill 根本没被执行。解决方案是在 Trae 的配置中关闭 header normalization，或在 Skill 前加一个兼容层。这提醒我：在分布式系统中，永远要怀疑“中间件”。

6. Skill 生态与未来演进：从单点工具到组织级能力网络

6.1 Skill 的复用与组合：超越“安装”，走向“编排”

一个 Skill 的价值，不仅在于它自身能做什么，更在于它如何与其他 Skill 协同。Trae 支持 Skill 组合（Composition），即一个 Skill 可以在其实现逻辑中，调用另一个 Skill。

例如，我们有一个git-diff-analyzerSkill，它接收 Git diff 文本，输出一个 JSON，包含“新增函数数”、“删除行数”、“高风险变更标记”。我们可以创建一个pr-quality-gateSkill，它的逻辑是：

1. 调用git-diff-analyzer分析本次 PR。
2. 如果“高风险变更标记”数量 > 3，则调用slack-notifySkill 发送警告。
3. 否则，调用jira-linkerSkill 自动关联 Jira ticket。

这个组合逻辑，不需要写新代码，只需在pr-quality-gate的 Code Block 中，用trae skill run git-diff-analyzer --input ...命令即可。Trae 会自动处理权限继承、输入输出转换、错误传播。

这种“Skill 编排”能力，让组织可以构建自己的“能力乐高”。市场部的同学可以组合content-generator+seo-analyzer+social-poster，形成一个“一键发布”流程；运维同学可以组合server-health-check+alert-sender+runbook-executor，形成一个“故障自愈”闭环。

6.2 Markdown 的深层价值：不止于语法，更是知识沉淀的载体

为什么 Trae 坚持用 Markdown？除了前面说的可读性、可版本化，还有一个被忽视的维度：知识沉淀。

一个写得好的 SKILL.md，本身就是一份微型文档。它包含了：

• What：description字段。
• Why：正文中“使用场景”部分。
• How：正文中“输入/输出示例”和“实现逻辑”部分。
• Who：triggers和environments定义了适用人群和场景。
• When：version和changelog（可选）记录了演进历史。

当一个 Skill 在团队中被广泛使用，它的 SKILL.md 就成了这个能力的“唯一真相源”（Single Source of Truth）。新人入职，看 SKILL.md 就能快速上手；审计人员，查 SKILL.md 就能