# rules-skills

本项目是一个 AI 编程辅助知识库，用于集中存放和管理常用的 **Rules（规则）** 与 **Skills（技能）**。

---

## 目录

- [概念定义](#概念定义)
- [核心区别](#核心区别)
- [目录结构](#目录结构)
- [使用方法](#使用方法)
- [书写规范](#书写规范)
- [文件命名规范](#文件命名规范)

---

## 概念定义

### Rule（规则）

**Rule** 是全局性的约束条件，用于划定 AI 的行为边界和输出规范。它告诉 AI "应该怎么做" 以及 "不应该做什么"。

- **作用范围**：全局生效，影响 AI 的所有响应
- **核心目的**：确保 AI 输出符合团队规范、编码标准或项目约束
- **典型场景**：
  - 代码风格规范（如必须使用某种命名约定）
  - 安全约束（如禁止输出敏感信息）
  - 输出格式要求（如必须包含特定字段）
  - 行为边界（如遇到不确定时必须询问而非猜测）

### Skill（技能）

**Skill** 是可复用的原子化能力单元，用于执行特定任务或完成特定目标。它告诉 AI "具体做什么" 以及 "如何一步步完成"。

- **作用范围**：按需调用，仅在触发时生效
- **核心目的**：封装可复用的任务执行流程，提高效率和一致性
- **典型场景**：
  - 代码审查流程
  - 特定框架的项目初始化
  - 标准化的文档生成
  - 重复的代码重构模式

---

## 核心区别

| 维度 | Rule（规则） | Skill（技能） |
|------|-------------|--------------|
| **本质定位** | 约束与边界 | 能力与动作 |
| **作用时机** | 全局持续生效 | 按需触发执行 |
| **内容形式** | 原则性、声明式描述 | 步骤化、流程化指导 |
| **使用方式** | 自动应用，无需显式调用 | 需要显式触发或调用 |
| **生命周期** | 长期稳定，少变更 | 随需求迭代，可增减 |
| **典型内容** | "必须使用驼峰命名"、"禁止硬编码密钥" | "1. 分析代码 2. 找出问题 3. 给出建议" |

### 类比理解

- **Rule** 像是交通规则：红灯停、绿灯行，所有车辆（AI 输出）都必须遵守。
- **Skill** 像是驾驶技能：倒车入库、侧方停车，需要时按步骤执行。

---

## 目录结构

```
rules-skills/
├── rules/                  # 存放所有 Rule 文件
│   ├── example-rule.md
│   └── ...
├── skills/                 # 存放所有 Skill 文件
│   ├── example-skill.md
│   └── ...
└── README.md               # 本文件
```

---

## 使用方法

### 使用 Rule

Rule 通常配置在 AI 工具的全局设置或项目配置中，自动生效：

1. 将需要的 Rule 文件内容复制到 AI 工具的规则配置区
2. 或在项目配置中引用 Rule 文件路径
3. AI 在处理所有请求时自动遵循这些规则

### 使用 Skill

Skill 需要显式触发，常见方式：

1. **命令触发**：在对话中直接引用 Skill 名称，如 `/skill-name` 或 `@skill-name`
2. **文件引用**：将 Skill 内容粘贴到对话中，让 AI 按步骤执行
3. **工具集成**：在支持 Skill 的 AI 平台中配置为可调用工具

---

## 书写规范

### Rule 书写规范

1. **明确性**：每条规则应清晰、无歧义，避免模糊表述
2. **可验证性**：规则应能被明确判断是否符合（是/否）
3. **必要性**：只写真正需要的规则，避免过度约束
4. **优先级**：如有多条规则冲突，应标明优先级
5. **格式统一**：建议使用 "必须..."、"禁止..."、"应该..." 等明确措辞

### Skill 书写规范

1. **步骤清晰**：将任务拆分为明确的步骤，每步一个动作
2. **输入输出定义**：明确 Skill 需要什么输入，产生什么输出
3. **可复用性**：设计时考虑通用性，避免过度绑定具体场景
4. **错误处理**：包含常见异常情况的应对方式
5. **示例说明**：提供 1-2 个使用示例，帮助理解

---

## 文件命名规范

### Rule 文件

- 使用 **kebab-case**（短横线连接）
- 格式：`{领域}-{具体规则}.md`
- 示例：
  - `code-style-java.md`
  - `security-sensitive-data.md`
  - `response-format-json.md`

### Skill 文件

- 使用 **kebab-case**（短横线连接）
- 格式：`{动作}-{目标}.md` 或 `{领域}-{动作}.md`
- 示例：
  - `review-code-java.md`
  - `generate-api-doc.md`
  - `refactor-extract-method.md`

---

## 贡献指南

1. 新增 Rule 或 Skill 前，先检查是否已有类似内容
2. 遵循上述书写规范和命名规范
3. 将文件放入对应的 `rules/` 或 `skills/` 目录
4. 保持内容简洁，聚焦单一职责
5. 定期回顾和维护，移除过时内容