Qoder Skills 从入门到落地：用标准工作流约束 AI 执行

需要访问外部系统数据或工具？           → MCP
只是全局行为约束？                   → Rules
只是一次性快捷动作？                 → Slash Command
需要复用的多步骤标准流程？             → Skill
需要外部工具 + 固定业务流程？          → MCP + Skill

your-skill-name/
├── SKILL.md
├── scripts/
│   ├── check_api_docs.py
│   └── validate.sh
├── references/
│   ├── api-guide.md
│   ├── examples.md
│   └── CHANGELOG.md
└── assets/
    ├── report-template.md
    └── logo.svg

npx skills add <skill-name>

目标 Agent：Qoder
安装级别：Global 或 Project
安装模式：copy

npx skills add from-design

~/.qoder/skills/from-design/

<项目根目录>/.qoder/skills/from-design/

# 用户级
mkdir -p ~/.qoder/skills
cp -r your-skill-name ~/.qoder/skills/

# 项目级
mkdir -p .qoder/skills
cp -r your-skill-name .qoder/skills/

帮我创建一个 Skill，用于在新增、修改或删除 API 接口时，
同步更新 OpenAPI 文档，检查兼容性，生成单元测试框架，
并记录 change log。

帮我新增一个用户登录接口，并检查接口文档和兼容性。

api-standard-check/
└── SKILL.md

---
name: api-standard-check
description: |
  当用户新增、修改或删除 API 接口时使用本 Skill。
  本 Skill 会要求同步 OpenAPI 文档、检查向后兼容性、生成单元测试框架，
  并以 change log 格式记录接口变更。
  触发词：新增接口、修改接口、删除接口、API 文档、接口兼容性、单元测试、接口变更。
license: MIT
metadata:
  version: 1.0.0
  owner: backend-team
  category: development
  tags:
    - api
    - openapi
    - testing
---

# API 标准变更流程

## 目标

当 API 发生新增、修改或删除时，确保代码、文档、兼容性检查、测试框架和变更记录同时完成。

## 重要约束

CRITICAL: 不允许只修改接口代码而不更新 OpenAPI 文档。

CRITICAL: 删除或修改已有接口前，必须检查是否破坏现有调用方。

## 执行步骤

### 1. 识别接口变更类型

判断当前任务属于以下哪一种：

- 新增 API
- 修改 API
- 删除 API

记录接口路径、HTTP 方法、请求参数、响应结构和错误码。

### 2. 修改接口代码

按项目现有代码风格实现接口逻辑。不要引入与项目技术栈不一致的新框架。

### 3. 同步 OpenAPI 文档

在 OpenAPI 文件中添加或更新对应接口，包括：

- path
- method
- request body
- query/path 参数
- response schema
- error response

### 4. 检查兼容性

检查以下内容：

- 是否删除了已有字段
- 是否改变了字段类型
- 是否改变了必填规则
- 是否改变了错误码语义
- 是否改变了认证或权限要求

如存在破坏性变更，必须明确提示，并给出兼容方案。

### 5. 生成单元测试框架

为新增或修改的接口生成测试，包括：

- 成功请求
- 参数缺失
- 参数非法
- 权限不足
- 典型业务异常

### 6. 记录 change log

按以下格式输出：

```text
## API Change Log

- Type: added | changed | removed
- Endpoint: METHOD /path
- Compatibility: compatible | breaking
- Document Updated: yes | no
- Tests Added: yes | no
- Notes:

这个 Skill 已经具备可用形态：有清晰触发条件、有强制约束、有执行步骤、有输出格式、有示例。

---

## 7. YAML Frontmatter 怎么写

Frontmatter 是 AI 判断“是否使用 Skill”的核心依据。写得太宽泛，会导致 Skill 被乱触发；写得太模糊，又可能该触发时没有触发。

### 7.1 必填字段

```yaml
---
name: api-standard-check
description: |
  当用户新增、修改或删除 API 接口时使用本 Skill。
  本 Skill 会同步 OpenAPI 文档、检查向后兼容性并生成单元测试框架。
  触发词：新增接口、接口文档、API 规范、兼容性检查、单元测试、接口变更。
---

只能使用小写字母、数字和短横线
不要使用空格
不要使用大写
不要使用保留词

name: api-standard-check

name: API Standard Check
name: api_standard_check
name: MySkill

---
name: data-report-generator
description: |
  当用户需要根据 CSV、数据库查询结果或业务指标生成分析报告时使用本 Skill。
  本 Skill 会完成数据检查、指标计算、异常点识别和报告输出。
license: MIT
allowed-tools: "Bash(python:*) WebFetch"
metadata:
  version: 1.0.0
  owner: data-team
  mcp-server: database
  category: analytics
  tags:
    - report
    - csv
    - data-analysis
    - dashboard
  documentation: https://example.com/docs/data-report-generator
---

description: 帮助处理项目。

description: 创建复杂的多页面文档系统。

description: |
  分析 Figma 设计文件并生成前端开发交付文档。
  当用户上传 .fig 文件，或提到“设计规范”“组件文档”“设计转代码”“前端切图”时使用。

description: |
  管理 Linear 项目工作流，包括 Sprint 规划、任务创建、状态跟踪和风险同步。
  当用户提到“冲刺”“项目计划”“创建工单”“排期”“任务状态”或“Linear 任务”时使用。

python scripts/check_api_docs.py --project .

## 文档一致性检查

在完成 API 代码修改后，运行：

```bash
python scripts/check_api_docs.py --project .

All API endpoints have matching OpenAPI documentation.

语言描述可以被误解，脚本执行结果更确定。适合脚本化的工作包括：

- 扫描 API 和文档是否一致
- 检查文件命名规范
- 校验 JSON、YAML、OpenAPI 格式
- 统计测试覆盖情况
- 生成固定格式报告
- 运行 lint、test、build

---

## 9. 三个典型使用场景

### 9.1 前端设计生成

很多 AI 生成的前端页面会有明显模板感：蓝白配色、常规卡片、默认字体、缺少层次。问题是用户很难说清楚“更好看”到底意味着什么。

设计类 Skill 可以把审美规则、字体选择、配色策略、布局方法、组件细节写进去。用户只描述产品目标，AI 根据 Skill 主动确认设计方向，再生成更完整的界面方案。

安装示例：

```bash
npx skills add from-design

帮我设计一个 Todo 应用首页，需要适合年轻用户，支持任务分组和今日重点任务。

npx skills add remotion-best-practice

帮我为一个 AI 电商图片处理工具制作中文宣传视频。
请先根据官网信息理解产品能力，再生成可下载的视频文件。

帮我创建一个 Skill。
当我新增、修改或删除 Java API 接口时，必须完成：
1. 同步更新 OpenAPI 格式的 API 文档
2. 检查新接口不破坏现有接口兼容性
3. 生成对应的单元测试框架
4. 以 change log 格式记录本次变更

请在这个 Skill 中添加一个 Python 脚本，
扫描项目内所有 API 接口，检查每个接口是否都有对应 OpenAPI 文档，
并以报告形式输出结果。

.qoder/skills/api-standard-check/
├── SKILL.md
└── scripts/
    └── check_api_docs.py

git add .qoder/skills/api-standard-check
git commit -m "feat: add api standard skill"
git push

git pull

## 工作流：新客户接入

### 1. 创建客户账户

调用客户系统 MCP，创建客户账户。

必须记录返回的 `customer_id`。

### 2. 设置支付方式

使用 `customer_id` 设置支付方式。

只有支付方式验证通过，才能进入下一步。

### 3. 创建订阅

基于 `customer_id` 和套餐类型创建订阅。

### 4. 发送欢迎邮件

调用邮件 MCP，使用 `welcome_email_template` 模板发送邮件。

### 失败处理

如果第 2 步失败，不允许创建订阅。
如果第 3 步失败，需要标记客户状态为 `pending_subscription`。

## 报告生成流程

### 1. 生成初稿

根据数据源生成第一版报告，并保存为临时文件。

### 2. 运行质量检查

执行：

```bash
python scripts/check_report.py --file report.md

循环要有退出条件，否则 AI 可能只修一次就结束。

### 10.4 上下文感知的工具选择

适合同一个目标在不同场景下使用不同工具。

```markdown
## 文件存储决策

### 1. 判断文件类型和大小

- 大于 10MB 的文件：使用云存储 MCP
- 协作文档：使用 Notion 或 Google Docs MCP
- 代码文件：使用 GitHub MCP
- 临时中间产物：使用本地存储

### 2. 执行存储

调用对应工具完成存储。

### 3. 说明原因

向用户说明为什么选择该存储方式。

## 支付处理合规流程

### 1. 处理前检查

获取交易详情，并检查：

- 制裁名单
- 司法管辖区
- 交易金额风险
- 历史欺诈记录

### 2. 决策

如果合规检查通过，调用支付处理工具。

如果检查不通过，禁止继续支付流程，并创建人工审核记录。

### 3. 审计记录

记录全部检查项、判断依据和处理结果。

帮我新增一个用户登录接口。
这个 API 和现有接口会不会冲突？
帮我写接口文档。
删除这个旧接口前帮我检查兼容性。
给这个接口补单元测试。

帮我写一首诗。
旧金山今天的天气怎么样？
帮我做一个旅行计划。
解释一下二叉树遍历。
把这段话翻译成英文。

你什么时候会使用 api-standard-check 这个 Skill？

刚才执行 api-standard-check 时遗漏了 DELETE 接口的兼容性检查。
请把这个要求固化到该 Skill 中：
当接口删除时，必须检查调用方、OpenAPI 文档、错误码和迁移说明。

.qoder/
└── skills/
    ├── api-standard-check/
    │   ├── SKILL.md
    │   └── scripts/
    │       └── check_api_docs.py
    └── release-checklist/
        └── SKILL.md

git add .qoder/skills
git commit -m "feat: add project skills"
git push

git commit -m "fix(skill/api-standard): check DELETE api compatibility"

metadata:
  version: 1.2.0
  owner: backend-team

# Changelog

## 1.2.0

- 增加 DELETE API 兼容性检查
- change log 输出增加 `Migration Required` 字段
- 删除接口时必须生成迁移说明

ls -la your-skill-folder/

SKILL.md

skill.md
SKILL.MD
Skill.md

name: my-skill
description: Does things

---
name: my-skill
description: Does things
---

---
name: my-skill
description: |
  当用户需要整理会议纪要时使用。
  本 Skill 会提取决策、行动项、负责人和截止日期。
---

1. 输入 `/`，确认 Skill 是否出现在列表中
2. 重启当前会话
3. 询问 AI 什么时候会使用该 Skill
4. 检查 description 是否包含当前任务的触发词
5. 临时使用 /skill-name 手动调用

description: |
  用于 CSV 文件的高级数据分析，包括统计建模、回归分析和聚类分析。
  不适用于简单表格查看、字段解释或普通数据查询。

description: |
  当用户完成 API 变更后生成发布说明时使用。
  如果项目中安装了 api-standard-check Skill，应先读取其 change log 输出。

第 1 步：安装一个开源 Skill

npx skills add from-design

选择 Qoder、Global、copy。

第 2 步：测试触发

在 Qoder Quest 模式输入一个前端设计需求。
如果没有自动触发，使用 /from-design 手动调用。

第 3 步：修改 description

打开：

~/.qoder/skills/from-design/SKILL.md

增加符合自己常用场景的触发词，保存后重启会话。

第 4 步：创建项目级 Skill

mkdir -p .qoder/skills/my-first-skill
touch .qoder/skills/my-first-skill/SKILL.md

第 5 步：提交给团队

git add .qoder/skills/my-first-skill
git commit -m "feat: add first project skill"
git push