AI技能到底是怎么写出来的:eCommerce-Skills的SKILL.md结构与最佳实践全解析
AI技能到底是怎么写出来的:eCommerce-Skills的SKILL.md结构与最佳实践全解析
eCommerce-Skills 是一个收录 157 个电商 AI 技能的开源项目,覆盖 Amazon、Shopify、Etsy、TikTok Shop 等平台的卖家场景。每个技能本质上就是一个 Markdown 文件——SKILL.md。本文带你拆解它的目录结构、YAML frontmatter 元数据与正文模块设计,总结出一套可以直接套用的 SKILL.md 编写最佳实践。
先建立直觉:一个技能就是一个文件夹
在 README.md 中,eCommerce-Skills 把"技能"定义为纯文本指令文件:没有二进制、没有 API Key、没有安装配置,LLM 读完 Markdown 就拥有了专家能力。
仓库里每个技能都遵循统一的目录约定:
| 组成部分 | 作用 | 是否必需 |
|---|---|---|
SKILL.md |
技能主体,指令与知识框架 | ✅ 必需 |
scripts/ |
Python 脚本,处理确定性计算 | 可选 |
agents/openai.yaml |
Agent 界面元数据(展示名、默认提示词) | 可选 |
evals/evals.json |
技能验收测试用例 | 可选 |
比如利润计算技能 profit-margin-calculator-amazon 就同时包含了 SKILL.md 和 scripts/calculator.py;而增长策略技能 ecommerce-growth-strategy/SKILL.md 则只有纯文本指令。这种"按需配附件"的思路值得借鉴:指令写进 SKILL.md,计算交给脚本,验收放进 evals。
YAML frontmatter:技能的"身份证"
新版技能文件以一段 YAML frontmatter 开头,例如 warehouse-optimization/SKILL.md:
---
name: warehouse-optimization
description: "E-commerce warehouse and inventory optimization advisor.
Analyzes inventory health, calculates safety stock..."
metadata: {"nexscope":{"emoji":"🏭","category":"ecommerce"}}
---
三个字段各有讲究:
- name:技能唯一标识,与安装命令
--skill <name>一一对应; - description:最重要的字段。它既要说明"能干什么",还要用
Use when: (1)...(2)...句式列出触发场景——这是 AI agent 判断"该不该调用这个技能"的核心依据; - metadata:emoji 和分类,用于技能市场的展示与检索。
一个小细节:仓库中 162 个 SKILL.md 里有 26 个旧文件(如 ebay-seo/SKILL.md)没有 frontmatter,直接以 # 标题 开头。项目是渐进式演进的,新技能才补齐了元数据区——如果你从零写技能,frontmatter 建议直接带上。
正文的十大标准模块
拆读 warehouse-optimization/SKILL.md、cross-border-ecommerce/SKILL.md 等完整版技能后,正文部分收敛为一套高度可复用的模块模板:
| # | 模块 | 写什么 | 示例位置 |
|---|---|---|---|
| 1 | H1 标题 + 一句话价值主张 | 3 行内说清"我是谁、帮你解决什么" | ecommerce-growth-strategy/SKILL.md |
| 2 | Install | 一行 npx skills add 安装命令 |
同上 #L24-L28 |
| 3 | Usage 示例 | 2~4 个自然语言提问示例,模拟真实用户口吻 | 同上 #L30-L45 |
| 4 | Capabilities / Features | 能力清单,最好用表格量化(如评分权重) | etsy-seo/SKILL.md |
| 5 | How This Skill Works | 分步骤工作流:收集信息→分析→输出 | cross-border-ecommerce/SKILL.md |
| 6 | First Interaction | 首次接触的开场白脚本,直接给出话术模板 | warehouse-optimization/SKILL.md |
| 7 | Handling Incomplete Input | 信息不全时的追问清单(Required / Recommended 分级) | warehouse-optimization/SKILL.md |
| 8 | Output Format | 报告模板,规定章节结构与表格样式 | cross-border-ecommerce/SKILL.md |
| 9 | Limitations | 诚实声明能力边界(税率会变、估算仅供方向参考等) | warehouse-optimization/SKILL.md |
| 10 | Related Skills | 交叉链接其他技能,形成技能网络 | ecommerce-growth-strategy/SKILL.md |
其中第 6、7、8 项是区分"普通文档"和"高质量技能"的分水岭:
💡 核心洞察:SKILL.md 的读者不是人,而是 AI agent。所以它不是"功能说明书",而是一份行为剧本——精确规定 agent 何时追问、追问什么、按什么格式输出。
例如 warehouse-optimization/SKILL.md 把建议分成 🔴 Critical(立即做)/ 🟡 Important(本月做)/ 🟢 Optimization(本季度做)三级,连输出的语气和优先级都被模板化了;review-checker/amazon-review-checker/SKILL.md 则设计了 L1-L4 渐进分析级别,"给的数据越多,分析越深",把交互深度也变成了可配置项。
三个进阶技巧:让技能超越纯文本
1️⃣ 用 scripts/ 目录承载确定性计算
纯指令无法保证每次计算结果一致。利润计算器把费率表和盈亏平衡公式固化在 calculator.py 中,SKILL.md 只负责告诉 agent"什么时候调用、如何传参、如何解读输出"。经验法则:知识写进 Markdown,计算写进 Python。
2️⃣ 用 agents/openai.yaml 定义 Agent 界面
如 competitive-pricing-strategy/agents/openai.yaml,三行元数据(display_name、short_description、default_prompt)让支持该协议的 agent 能自动生成按钮和默认提示词,属于低成本高回报的兼容性配置。
3️⃣ 用 evals/evals.json 给技能做单元测试
warehouse-optimization/evals/evals.json 定义了 5 组"提示词 + 期望输出"用例,覆盖 IPI 分数诊断、安全库存计算、ABC 分析等典型场景。修改技能后跑一遍用例,就能验证能力没有退化——这是仓库里最值得抄的工程质量实践。
可直接套用的 SKILL.md 编写清单
结合上述结构,一份合格的 SKILL.md 按顺序包含 7 步:
- 写 frontmatter:
name+ 带 "Use when" 触发句的description+ emoji 元数据; - 一句话价值主张:H1 之下 1~3 行,说清为谁解决什么问题;
- 给出安装命令和使用示例:让用户 30 秒内能跑起来;
- 能力清单表格化:能评分的就给权重(参考 etsy-seo/SKILL.md),能分级的就给级别;
- 写出完整工作流:Step 1 收集 → Step N 输出,每步可执行、可检查;
- 定义输出模板和边界:报告长什么样、哪些事情"不保证",都要写明;
- 交叉链接相关技能:策略层指向执行层,形成技能生态。
安装体验也很轻,一条命令即可全部装好:
npx skills add nexscope-ai/eCommerce-Skills -g
总结
eCommerce-Skills 的 157 个技能证明了一件事:AI 技能的竞争力不在代码量,而在指令设计的质量。frontmatter 决定"何时被调用",工作流与输出模板决定"被调用时表现如何",scripts 与 evals 决定"结果是否稳定可信"。仓库只读、结构清晰,把 ecommerce-growth-strategy/SKILL.md、cross-border-ecommerce/SKILL.md 和 warehouse-optimization/SKILL.md 当作范文通读一遍,再对照本文的 7 步清单动手写,你就能产出同水准的 SKILL.md 了。
