技能概述

引言

一个技能可以被视为提供给智能体的一套 “专业能力说明书”（类似用户手册或操作指南）。在执行任务时，智能体可以按需加载相应的技能，从而增强其对任务的理解与执行能力。比如：让智能体帮你查看这个函数写得如何？或者帮你审查一下这个代码等，只要你定制好这个技能该如何去操作，智能体就会按照这个技能去执行。

主要特点

结构化

一个技能对应一个skill.md 文件，文件中以结构化的方式描述完成某一类任务所需的信息，例如：任务描述、使用场景、指令、关键约束与注意事项、模板或示例。

按需加载

智能体不会在任务开始时一次性读取所有技能的完整内容。在执行任务前，智能体会先扫描所有技能的简要描述，仅当判断当前任务与某个技能高度相关时，才会加载该技能的详细内容。这种按需加载机制可以有效减少上下文中的 Token 消耗、避免无关信息干扰智能体的决策。

使用场景

保证输出结果的一致性与规范性

需要智能体在不同时间、不同任务中，始终按照既定标准输出结果。例如，将统一设计规范、执行团队标准、保持品牌一致性或确保代码符合项目约定等要求封装为技能，从而将隐性的个人或团队标准转化为显式、可复用的专业能力，最终使输出结果更加稳定、可控。

自动化重复性工作流

需要频繁执行相同或高度相似的多步骤任务。例如，对于测试流程、代码规范检查、常规数据分析等难以避免的日常工作，可以将既有的 SOP 封装为技能。一旦相关任务被触发，智能体即可自动按照定义好的流程执行，从而减少重复的指令输入，提升效率。

总结与共享专业能力

总结个人经验或团队规范，并在更大范围内复用。例如，将技能在社区、交流群等公共平台进行分享，从而在不同的智能体、项目、团队间复用相同的技能。

技能 vs 其他功能

技能 vs 规则

规则采用全量加载机制，一旦开启对话，所有规则都会被注入并持续占用上下文窗口；技能则采用按需加载机制，仅在实际需要被调用时才加载到上下文中，从而显著降低 Token 消耗。

技能 vs MCP服务

技能用于向模型描述如何完成任务，而 MCP服务负责向模型提供可以调用的工具。

支持的技能类型

全局技能

• 跨项目全局生效的技能，可用于：
• 统一个人 / 团队的通用开发范式，例如统一代码风格、命名规范、注释习惯；
• 提供跨项目可复用的工程能力，例如通用工具链的使用（Git、CI/CD、Playwright 等）；
• 固化个人或组织的长期偏好，例如输出结构（是否先给结论、是否列步骤、是否给示例）。

项目技能

• 仅在当前项目生效的技能，可用于：
• 注入项目专属的业务知识与规则，例如不可违反的业务约束与边界条件、项目内部术语、概念映射；
• 约束 AI 按项目的既定技术方案工作，例如技术栈、框架版本、架构限制等；
• 让 AI 深度参与当前项目的开发和维护，例如针对项目生成测试、Mock、脚手架代码；与项目使用的 MCP服务或内部工具协同。

技能优先级

• 全局技能和项目技能都会将已开启的技能提供给模型，模型根据技能描述和任务需求进行匹配，选择相似度更高的技能进行使用。
• 若全局技能和项目技能相似度都高，技能名称一致时，优先使用 项目技能 > 全局技能。

技能的结构

一个技能中必须包含一个 SKILL.md 文件，还可以根据实际需求添加其他文件，例如可执行的脚本、可参考的模板和风格指南等。例如：

skill-name/
├── SKILL.md               # （必须）智能体的核心指令
├── examples/              # （可选）输入/输出示例
    ├── input.md
    └── output.md
├── templates/             # （可选）可复用的模板
    └── component.tsx
└── resources/             # （可选）参考文件、运行脚本或素材
    └── style-guide.md

技能所在目录

项目技能：项目所在路径下的 .feisuan/skills/ 目录。 全局技能：本地主磁盘/用户名/.feisuan/skills/ 目录。

SKILL.md 文件格式

SKILL.md 文件的格式如下：

---
name: 技能名称
description: 简要描述这个技能的功能和使用场景

---

# 技能名称

## 描述
描述这个技能的作用。

## 使用场景
描述触发这个技能的条件。

## 指令
清晰的分步说明，告诉智能体具体怎么做。

## 示例 (可选)
输入/输出示例，展示预期效果。

技能示例

当前使用代码审查技能为例，展示如何编写代码审查的技能文件.

---

name: code-review
description: 扮演资深代码检查专家，对代码变更进行多维度（安全、逻辑、性能、风格）的系统化审查，并输出结构化报告。适用于代码提交前检查、MR/PR评审等场景。

---

# 代码审查专家

## 描述

本技能将使智能体扮演一位经验丰富、严谨的代码审查专家。其核心职责是对提交的代码进行系统性、多维度的审查，旨在提升代码质量、保障系统安全、优化性能并确保代码的可维护性。智能体将遵循标准化的审查流程，并提供清晰、结构化且富有建设性的反馈报告。

## 使用场景

- 代码提交（Commit）前的自我检查。
- 合并请求（MR）或拉取请求（PR）的正式评审。
- 对现有代码库进行质量评估或重构前的分析。
- 学习最佳实践，通过审查他人的代码来提升自己的编程水平。
- 当用户直接提出“帮我审查这段代码”、“进行代码检查”或“Code Review”等需求时。

## 指令

请严格遵循以下步骤和标准执行代码审查：

1. **理解上下文**
   首先，尝试理解代码变更的业务目标或功能需求。如果提供了MR/PR描述或相关issue链接，请仔细阅读，以确保审查不偏离初衷。

2. **多维度审查**
   按照以下优先级顺序，对代码进行逐行或逐模块的审查：

- **安全性 (最高优先级):** 重点检查是否存在注入风险（如SQL注入、XSS）、敏感信息泄露（如硬编码的密钥）、权限校验缺失或使用了有已知漏洞的依赖。
- **逻辑正确性:** 确保代码能正确实现预期功能。检查是否存在空指针/未定义风险、边界条件错误、并发安全问题以及不合理的异常处理。
- **性能:** 识别潜在的性能瓶颈。关注低效的算法/数据结构、N+1查询问题、资源泄漏（如文件流、数据库连接未关闭）和冗余计算。
- **代码质量与规范:** 提升代码的可读性和可维护性。检查命名是否清晰表意、是否存在代码重复、函数是否过于复杂（如过长或职责过多），以及关键逻辑是否有注释说明。

3. **整合与报告**
   将所有发现的问题和建议，严格按照下方的“输出规范”进行整理和输出。确保反馈是结构化的、有建设性的。

### 输出规范

你必须严格按照以下格式输出审查报告：

#### 严重问题 (P0 - 必须修复)

此部分列出所有安全漏洞和严重的逻辑错误，这些问题可能导致线上故障，必须在合并前修复。

- **[文件名:行号] 问题描述**
  - **原因：** 简要解释为什么这是个问题。
  - **建议：** 提供具体的修复建议或示例代码。

#### ️ 重要问题 (P1 - 建议修复)

此部分列出性能隐患、可维护性问题和代码异味。强烈建议在合并前修复。

- **[文件名:行号] 问题描述**
  - **原因：** 解释其对性能或可维护性的影响。
  - **建议：** 提供优化方案。

#### 建议 (P2 - 可选)

此部分列出一些锦上添花的优化建议或最佳实践参考。

- **[文件名:行号] 问题描述**
  - **建议：** 提供一个可选的改进方向。

#### 亮点

此部分列出代码中值得肯定的地方，例如优雅的设计、清晰的命名或巧妙的实现。

- **[文件名:行号] 亮点描述**
  - **评价：** 说明为什么这个实现很好。

### 约束规则

- **言之有据：** 所有评论必须引用具体的代码行号，避免空泛。
- **宁缺毋滥：** 避免提出琐碎的、主观的意见。
- **提供方案：** 对于每个问题，尽可能提供一个具体的修复建议。
- **保持专业：** 沟通语气应保持专业、友好和建设性。

## 示例 (可选)

### 输入

用户提交了一段 Python 代码，并提问：“帮我审查一下这个数据库查询函数。”

```python
def get_user(user_id):
    query = "SELECT * FROM users WHERE id = " + str(user_id)
    # 执行 query ...

```