Run any Skill in Manus with one click

Get Started

common-project-standard

Stars625

Forks112

UpdatedJune 24, 2026 at 23:18

项目规范技能，提供项目结构、文档管理、代码忽略等方面的标准和最佳实践

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

bage2014

bage2014/study

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

SKILL.md

readonly

项目规范技能

功能描述

提供项目结构、文档管理、代码忽略等方面的标准和最佳实践，帮助团队建立统一的项目规范。同时提供技能规范验证工具和开源技能包装机制。

何时使用

在以下情况调用此技能：

创建新项目时
维护现有项目时
需要制定项目规范时
需要验证技能规范性时
需要集成开源技能时

核心功能

技能管理：规范技能的创建和管理流程
文档管理：规范文档的编写和维护标准
Git忽略：规范 .gitignore 文件的配置
AI忽略：规范 AI 相关文件的忽略规则
项目结构：规范项目目录结构
技能安装：提供技能安装和配置指导
规范验证：验证技能是否符合标准格式
开源集成：支持开源技能的包装和切换

输入参数

参数	类型	必填	说明
projectType	String	否	项目类型（backend/frontend/fullstack）
framework	String	否	使用的框架
validateSkills	Boolean	否	是否验证技能规范
openSourceSkills	List	否	要集成的开源技能列表

输出格式

{
  "status": "SUCCESS",
  "projectType": "backend",
  "framework": "Spring Boot",
  "guidelines": {
    "skill": {...},
    "documentation": {...},
    "gitignore": {...},
    "aiIgnore": {...},
    "structure": {...},
    "installation": {...},
    "validation": {...},
    "openSourceIntegration": {...}
  }
}

1. 技能管理规范

1.1 技能目录结构

skills/
├── skill-name/           # 技能名称（小写连字符）
│   └── SKILL.md          # 技能定义文件（必填）

1.2 技能命名规范

类型	前缀	示例
异常分析	`exception-`	`exception-analysis`
AI 聊天	`spring-ai-`	`spring-ai-chat`
研发流程	`common-`	`common-coding`, `common-test`
个人技能	`personal-`	`personal-backend-coding-standard`
项目规范	`common-project-`	`common-project-standard`
开源包装	`os-`	`os-ui-library`, `os-chat-model`

1.3 SKILL.md 文档结构

---
name: "skill-name"
description: "技能描述，简要说明技能的核心价值和用途"
trigger: "触发条件，简洁描述技能何时被触发"
disable-when: "禁用条件，描述不适合使用此技能的场景"
category: "技能分类，如：backend/frontend/database/devops/ai"
tags: ["标签1", "标签2"]
requires: ["依赖技能1", "依赖技能2"]
---

# 技能名称

## 功能描述
## 触发条件
## 何时使用
## 何时不使用
## 核心功能
## 输入参数
## 输出格式
## 使用流程
## 调用示例
## 失败案例
## 最佳实践
## 配置要求
## 扩展指南

1.3.0 Frontmatter 元数据规范

Frontmatter 是技能的元数据定义区，用于描述技能的基本信息和属性：

字段	类型	必要性	说明
name	String	必填	技能名称，必须与目录名一致
description	String	必填	技能的核心价值和用途描述（1-2句话）
trigger	String	必填	触发条件，简洁描述技能何时被触发
disable-when	String	必填	禁用条件，描述不适合使用此技能的场景
category	String	必填	技能分类（backend/frontend/database/devops/ai等）
tags	Array	推荐	技能标签，用于分类和搜索
requires	Array	可选	依赖的其他技能名称

Frontmatter 示例：

---
name: "common-spring-boot-init"
description: "快速创建 Spring Boot 项目结构，支持多种数据库和依赖配置"
trigger: "用户请求创建新的 Spring Boot 项目时"
disable-when: "项目已存在或非 Java 技术栈项目"
category: "backend"
tags: ["spring", "java", "backend", "project-init"]
requires: ["common-db-design"]
---

1.3.1 文档章节说明

章节	必要性	说明
功能描述	必填	技能的核心能力和价值定位
触发条件	必填	技能被触发执行的条件和前置要求
何时使用	必填	适合使用此技能的场景
何时不使用	推荐	不适合使用此技能的场景（禁用样例）
核心功能	必填	技能提供的具体功能列表
输入参数	必填	输入参数定义（表格形式）
输出格式	必填	输出数据格式（JSON示例）
使用流程	推荐	使用该技能的步骤说明
调用示例	推荐	实际使用的代码或命令示例
失败案例	推荐	常见错误场景及解决方案
最佳实践	推荐	使用该技能的最佳实践建议
配置要求	可选	环境变量、配置文件等要求
扩展指南	可选	如何扩展或定制该技能

1.3.2 触发条件规范

触发条件应明确以下内容：

前置条件：使用技能前必须满足的条件
环境要求：所需的软件、依赖、权限等
数据准备：需要预先准备的数据或配置
触发方式：技能被调用的方式（API、命令行、事件等）

示例格式：

## 触发条件

- **前置条件**：项目已初始化，具备基础目录结构
- **环境要求**：Java 21+, Maven 3.8+, Spring Boot 3.2+
- **数据准备**：配置文件 `application.yml` 已存在
- **触发方式**：API 调用 / 命令行执行 / 事件触发

1.3.3 何时不使用（禁用样例）

明确列出不适合使用此技能的场景：

示例格式：

## 何时不使用

- 当项目已使用其他 ORM 框架时，不建议使用此技能
- 简单的 CRUD 操作无需使用此技能
- 需要复杂事务管理的场景请使用其他方案

1.3.4 失败案例规范

记录常见的失败场景及解决方案：

示例格式：

## 失败案例

| 错误场景 | 错误信息 | 解决方案 |
|----------|----------|----------|
| 数据库连接失败 | `Connection refused` | 检查数据库服务是否启动 |
| 权限不足 | `Permission denied` | 确认用户有足够的文件权限 |
| 依赖缺失 | `ClassNotFoundException` | 检查 pom.xml 依赖配置 |

1.4 技能注册流程

在 skills/ 目录下创建技能目录
创建 SKILL.md 文件
在 AGENTS.md 中添加技能说明
在 SKILLS.md 中注册技能

2. 文档管理规范

2.1 文档目录结构

docs/
├── api/                  # API 文档
│   └── openapi.yaml
├── architecture/         # 架构文档
│   └── architecture.md
├── guides/               # 使用指南
│   └── getting-started.md
├── README.md             # 项目说明（根目录）
├── AGENTS.md             # 代理与技能架构（根目录）
└── SKILLS.md             # 技能清单（根目录）

2.2 文档命名规范

类型	命名规则	示例
文档文件	小写连字符	`getting-started.md`
目录名称	小写连字符	`api/`, `guides/`

2.3 文档模板

README.md 模板

# 项目名称

## 项目简介
## 技术栈
## 快速开始
## 项目结构
## API 接口
## 开发指南
## 部署说明
## 贡献指南
## 许可证

SKILLS.md 模板

# 技能清单

## 个人定制技能

| 技能名称 | 描述 |
|----------|------|
| personal-backend-coding-standard | 后端编码规范技能 |
| personal-frontend-coding-standard | 前端编码规范技能 |

## 通用技能

| 技能名称 | 描述 |
|----------|------|
| common-project-standard | 项目规范技能 |
| common-contract-generation | 契约生成技能 |
| common-frontend-playwright-test | 前端Playwright测试技能 |
| common-backend-unit-test | 后端单元测试技能 |
| common-coding | 编码技能 |
| common-requirement-clarification | 需求澄清技能 |

## 功能技能

| 技能名称 | 描述 |
|----------|------|
| spring-ai-chat | Spring AI 聊天集成 |
| model-provider-creator | 模型提供商创建器 |
| mcp-tool-creator | MCP工具创建器 |
| plan-executor | 计划执行器 |
| exception-analysis | 异常分析技能 |

## 开源技能包装

| 技能名称 | 描述 | 底层实现 |
|----------|------|----------|
| os-ui-library | UI组件库技能 | 可配置（自研/Component-A/Component-B） |
| os-chat-model | 聊天模型技能 | 可配置（OpenAI/DeepSeek/Claude） |

AGENTS.md 模板

# 代理与技能架构

## 概述

本项目使用 Trae AI 技能系统，通过技能扩展项目能力。

## 技能目录

所有技能位于 `skills/` 目录下。

## 技能分类

### 个人定制技能
- personal-backend-coding-standard - 后端编码规范
- personal-frontend-coding-standard - 前端编码规范

### 通用技能
- common-project-standard - 项目规范
- common-contract-generation - 契约生成
- common-frontend-playwright-test - 前端测试
- common-backend-unit-test - 后端测试
- common-coding - 编码规范
- common-requirement-clarification - 需求澄清

### 功能技能
- spring-ai-chat - AI 聊天功能
- model-provider-creator - 模型提供商
- mcp-tool-creator - MCP工具创建
- plan-executor - 计划执行器
- exception-analysis - 异常分析

### 开源技能包装
- os-ui-library - UI组件库（可切换实现）
- os-chat-model - 聊天模型（可切换实现）

## 技能使用方式

### 1. 安装技能

使用项目根目录的 `install-skills.sh` 脚本安装技能：

```bash
# 安装所有技能
./install-skills.sh /path/to/project

# 安装指定技能
./install-skills.sh -s common-coding -s common-project-standard .

2. 注册技能

在 SKILLS.md 中注册技能，系统会自动加载。

3. 使用技能

在需要时调用相应的技能接口。

4. 验证技能规范

# 验证所有技能
./validate-skills.sh

# 验证指定技能
./validate-skills.sh -s common-coding

# 修复技能格式
./validate-skills.sh -f


### 2.4 文档编写规范

1. **语言**：统一使用中文
2. **格式**：使用 Markdown 格式
3. **标题**：使用 `#` 表示标题层级
4. **代码块**：使用三个反引号 + 语言标识
5. **链接**：使用绝对路径或相对路径

---

## 3. Git 忽略规范

### 3.1 .gitignore 文件位置

- 根目录：`.gitignore` - 全局忽略规则
- 模块目录：`module/.gitignore` - 模块特定规则

### 3.2 通用忽略规则

```gitignore
# 构建产物
target/
build/
dist/
*.class
*.jar
*.war

# IDE 文件
.idea/
.vscode/
.project
.classpath
.settings/

# 日志文件
*.log
logs/

# 配置文件
application-local.yml
application-local.properties
.env

# OS 文件
.DS_Store
Thumbs.db

# Maven
.mvn/
mvnw
mvnw.cmd

# Gradle
.gradle/
gradlew
gradlew.bat

3.3 后端项目忽略规则

# 数据库文件
*.db
*.sqlite

# JVM 相关
hs_err_pid*
replay_pid*

# Spring Boot
spring-shell.log

3.4 前端项目忽略规则

# Node.js
node_modules/
package-lock.json
yarn.lock

# 构建工具
.next/
.nuxt/
.svelte-kit/

# TypeScript
*.tsbuildinfo

4. AI 忽略规范

4.1 AI 相关文件识别

类型	描述	示例
模型文件	训练好的 AI 模型	`model.pt`, `model.onnx`
数据集	训练数据	`data/`, `dataset/`
缓存文件	AI 工具生成的缓存	`.cache/`, `__pycache__/`
向量数据库	向量索引文件	`chroma/`, `pinecone/`

4.2 AI 忽略规则

# AI 模型文件
*.pt
*.pth
*.onnx
*.h5
*.bin
*.ckpt

# 数据集
data/
dataset/
datasets/

# 向量数据库
chroma/
pinecone/
qdrant/
weaviate/

# 缓存目录
.cache/
__pycache__/
.huggingface/
.tensorflow/

# 模型下载目录
models/
downloads/
checkpoints/

4.3 AI 配置文件管理

# API Key 文件
*.key
*.secret
api-keys.json

# 配置文件
config/secrets.yml
config/secrets.json

# 环境变量
.env.local
.env.production

5. Trae 忽略规范

5.1 .traeignore 文件位置

根目录：.traeignore - 全局 Trae 忽略规则

5.2 .traeignore 作用

.traeignore 文件用于指定 Trae AI 系统应忽略的文件和目录，这些文件不会被技能系统加载或处理。

5.3 .traeignore 标准配置

# 技能缓存目录
.cache/
.skills-cache/

# 技能临时文件
*.tmp
*.temp

# 技能索引文件
skills-index.json
skills-mapping.json

# 日志文件
*.log
logs/

# 测试文件
__tests__/
*.test.js
*.spec.js

# 编辑器文件
.vscode/
.idea/
*.swp
*.swo
*~

# 系统文件
.DS_Store
Thumbs.db

# 技能开发文件
dev/
examples/
samples/

# 技能模板文件
*.template
*.stub

# 技能打包文件
*.zip
*.tar.gz
*.tgz

# 依赖目录
node_modules/
vendor/

# 构建产物
dist/
build/

5.4 .traeignore 与 .gitignore 的区别

文件	作用	适用范围
`.gitignore`	版本控制忽略	Git 仓库
`.traeignore`	技能系统忽略	Trae AI 技能加载

5.5 联合使用建议

项目根目录
├── .gitignore          # Git 版本控制忽略
├── .traeignore         # Trae 技能系统忽略
└── .trae/
    ├── skills/         # 技能目录（Git 追踪，Trae 加载）
    └── cache/          # 缓存目录（Git 忽略，Trae 忽略）

5.6 示例配置

项目根目录 .gitignore：

# Trae 缓存目录
.trae/cache/
.trae/.cache/

# Trae 临时文件
.trae/*.tmp

项目根目录 .traeignore：

# 忽略技能开发目录
dev/
examples/

# 忽略测试文件
__tests__/
*.test.js

# 忽略编辑器配置
.vscode/
.idea/

技能目录 .traeignore（可选）：

# 技能内部忽略规则
node_modules/
*.log

6. 项目结构规范

6.1 后端项目结构

xx-parent/                     # Maven 父模块
├── pom.xml                    # 父 POM 配置
├── xx-gateway/               # 网关模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/gateway/
│       └── resources/
├── xx-biz/                   # 业务模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/biz/
│       └── resources/
├── xx-infra/                 # 基础设施模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/infra/
│       └── resources/
└── .trae/                    # 技能目录
    └── skills/

6.2 模块职责说明

模块	职责	说明
`xx-gateway`	请求路由和认证	处理外部请求，进行认证授权
`xx-biz`	核心业务逻辑	实现业务功能，处理业务规则
`xx-infra`	基础设施支持	公共组件、工具类、配置

6.3 包结构规范

com/bage/xx/
├── controller/          # REST API 控制层
├── service/             # 业务逻辑层
│   └── impl/           # 服务实现
├── repository/          # 数据访问层
├── entity/              # 数据库实体
├── dto/                 # 数据传输对象
│   ├── request/        # 请求 DTO
│   └── response/       # 响应 DTO
├── config/              # 配置类
├── exception/           # 自定义异常
└── util/                # 工具类

7. 技能安装与配置

7.1 安装方式

使用安装脚本（推荐）

# 从 skills 仓库安装到目标项目
bash <(curl -s https://raw.githubusercontent.com/your-repo/study-ai-skills/main/install-skills.sh) /path/to/your/project

# 或者克隆仓库后安装
git clone https://github.com/your-repo/study-ai-skills.git
cd study-ai-skills
./install-skills.sh /path/to/your/project

手动安装

# 创建技能目录
mkdir -p /path/to/your/project/.trae/skills

# 复制技能（以 common-project-standard 为例）
cp -r /path/to/study-ai-skills/skills/common-project-standard /path/to/your/project/skills/

7.2 安装脚本使用说明

# 查看帮助
./install-skills.sh -h

# 列出所有可用技能
./install-skills.sh -l

# 安装所有技能到当前目录
./install-skills.sh .

# 安装所有技能到指定目录
./install-skills.sh /path/to/project

# 安装指定技能
./install-skills.sh -s common-coding -s personal-backend-coding-standard .

# 强制覆盖已存在的技能
./install-skills.sh -f -s common-project-standard .

# 交互式安装
./install-skills.sh -i

# 指定IDE安装
./install-skills.sh --ide trae .

7.3 配置文件

创建 .trae/config.yml 配置文件：

# .trae/config.yml
skills:
  # 是否自动加载所有技能
  auto-load: true
  
  # 技能搜索路径
  paths:
    - .trae/skills
  
  # 默认启用的技能
  enabled:
    - personal-backend-coding-standard
    - personal-frontend-coding-standard
    - common-project-standard
    - common-coding
    - common-contract-generation
    - common-backend-unit-test
    - common-frontend-playwright-test
    - common-requirement-clarification
    - spring-ai-chat
    - model-provider-creator
    - mcp-tool-creator
    - plan-executor
    - exception-analysis

6.4 全局配置（推荐）

在用户主目录创建配置文件，使所有项目默认使用这些技能：

# 创建全局配置目录
mkdir -p ~/.trae

# 创建全局技能配置
cat > ~/.trae/skills-config.yml << 'EOF'
# 全局技能配置
skills:
  # 技能仓库位置
  repository: ~/bage/github/study/study-ai-skills/.trae/skills
  
  # 默认启用的技能
  default-enabled:
    - personal-backend-coding-standard
    - personal-frontend-coding-standard
    - common-project-standard
    - common-coding
  
  # 自动同步更新
  auto-sync: true
EOF

# 创建全局安装脚本链接
ln -sf ~/bage/github/study/study-ai-skills/install-skills.sh ~/.trae/install-skills.sh

# 添加到 PATH
echo 'export PATH="$HOME/.trae:$PATH"' >> ~/.bashrc
echo 'export PATH="$HOME/.trae:$PATH"' >> ~/.zshrc

8. 技能规范验证

8.1 验证脚本使用

# 验证所有技能
./validate-skills.sh

# 验证指定技能
./validate-skills.sh -s common-coding

# 列出所有技能
./validate-skills.sh -l

# 修复技能格式
./validate-skills.sh -f

# 修复指定技能
./validate-skills.sh -f -s common-coding

8.2 验证规则

检查项	说明	级别
SKILL.md 存在	技能目录必须包含 SKILL.md	错误
Frontmatter 完整	必须包含 name 和 description 字段	错误
name 匹配目录名	name 字段值应与目录名一致	警告
功能描述章节	必须包含 ## 功能描述	警告
何时使用章节	必须包含 ## 何时使用	警告
核心功能章节	必须包含 ## 核心功能	警告
输入参数章节	必须包含 ## 输入参数	警告
输出格式章节	必须包含 ## 输出格式	警告
输入参数表格	输入参数章节应包含表格	警告
输出格式示例	输出格式章节应包含示例	警告

8.3 修复功能

验证脚本的 -f 参数可以自动修复以下问题：

创建缺失的 SKILL.md 文件
添加缺失的 Frontmatter 字段
添加缺失的章节标题

9. 开源技能包装机制

9.1 设计理念

为了支持多种实现的切换，开源技能采用包装模式：

┌─────────────────────────────────────────────────────┐
│                    技能接口层                       │
│              (Skill Interface)                      │
│  ┌─────────────────────────────────────────────┐   │
│  │  - 统一的输入参数                            │   │
│  │  - 统一的输出格式                            │   │
│  │  - 统一的调用方式                            │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│                    实现切换层                       │
│              (Implementation Switch)               │
│  ┌─────────────────────────────────────────────┐   │
│  │  - 配置驱动的实现选择                         │   │
│  │  - 运行时动态切换                           │   │
│  │  - 实现隔离与解耦                           │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│  自研实现     │ │ 开源实现 A    │ │ 开源实现 B    │
│ (Default)    │ │ (OpenSourceA) │ │ (OpenSourceB) │
└───────────────┘ └───────────────┘ └───────────────┘

9.2 技能命名约定

前缀	说明	示例
`os-`	开源技能包装	`os-ui-library`, `os-chat-model`
`os-{name}-impl-`	具体实现	`os-ui-library-impl-native`, `os-ui-library-impl-componenta`

9.3 配置方式

# .trae/config.yml
skills:
  open-source:
    # UI组件库实现选择: native/componenta/componentb
    os-ui-library:
      active: native
      implementations:
        - name: native
          description: 自研轻量级实现
          enabled: true
        - name: componenta
          description: 基于 Component Library A
          enabled: true
          dependencies:
            - "@componenta/core"
        - name: componentb
          description: 基于 Component Library B
          enabled: false
          dependencies:
            - "@componentb/react"
    
    # 聊天模型实现选择: openai/deepseek/claude
    os-chat-model:
      active: deepseek
      implementations:
        - name: openai
          description: OpenAI API
          enabled: true
          env:
            - OPENAI_API_KEY
        - name: deepseek
          description: DeepSeek API
          enabled: true
          env:
            - DEEPSEEK_API_KEY
        - name: claude
          description: Claude API
          enabled: true
          env:
            - CLAUDE_API_KEY

9.4 开源技能包装示例

技能目录结构

skills/
├── os-ui-library/                    # 包装技能（统一接口）
│   └── SKILL.md
├── os-ui-library-impl-native/        # 自研实现
│   └── SKILL.md
├── os-ui-library-impl-componenta/    # 组件库A实现
│   └── SKILL.md
└── os-ui-library-impl-componentb/    # 组件库B实现
    └── SKILL.md

SKILL.md 包装层示例

---
name: "os-ui-library"
description: "UI组件库技能 - 支持多种实现切换"
---

# UI组件库技能

## 功能描述

提供统一的 UI 组件库接口，支持多种实现切换。

## 何时使用

需要使用 UI 组件时，通过配置选择不同实现。

## 核心功能

- 统一的组件接口
- 运行时实现切换
- 多种开源组件库支持

## 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| componentType | String | 是 | 组件类型 |
| props | Object | 否 | 组件属性 |
| implementation | String | 否 | 指定实现（native/componenta/componentb） |

## 输出格式

```json
{
  "status": "SUCCESS",
  "implementation": "native",
  "component": {...}
}

实现配置

在 .trae/config.yml 中配置：

skills:
  open-source:
    os-ui-library:
      active: native

可用实现

实现名称	描述	状态
native	自研轻量级实现	✅
componenta	基于 Component Library A	✅
componentb	基于 Component Library B	⚠️


### 9.5 切换实现流程

```bash
# 查看当前配置
cat .trae/config.yml | grep -A 5 "os-ui-library"

# 切换到 Component Library A
sed -i '' 's/active: native/active: componenta/' .trae/config.yml

# 安装依赖（如果需要）
npm install @componenta/core

# 验证切换
./validate-skills.sh -s os-ui-library

10. 代码审查检查清单

检查项	说明	状态
技能结构	技能目录和文件是否符合规范	✅/❌
文档完整性	是否有必要的文档说明	✅/❌
Git忽略	.gitignore 是否完整	✅/❌
AI忽略	AI 相关文件是否正确忽略	✅/❌
Trae忽略	.traeignore 是否完整	✅/❌
项目结构	目录结构是否符合规范	✅/❌
命名规范	文件和目录命名是否符合规范	✅/❌
技能注册	是否在 SKILLS.md 中注册	✅/❌
规范验证	是否通过技能规范验证	✅/❌
开源包装	开源技能是否符合包装规范	✅/❌

11. 配置要求

11.1 环境变量

变量名	说明	默认值
PROJECT_NAME	项目名称	-
PROJECT_TYPE	项目类型	backend
TRAE_SKILLS_PATH	技能目录路径	.trae/skills

11.2 配置文件

project:
  name: xx
  type: backend
  modules:
    - gateway
    - biz
    - infra

skills:
  auto-load: true
  paths:
    - .trae/skills
  open-source:
    os-ui-library:
      active: native
    os-chat-model:
      active: deepseek

12. 扩展指南

12.1 添加新技能

在 skills/ 目录下创建新目录
创建 SKILL.md 文件
在 AGENTS.md 中注册技能
在 SKILLS.md 中添加技能清单
使用 ./validate-skills.sh 验证格式

12.2 添加开源技能包装

创建包装层技能（os-{name}）
创建各实现技能（os-{name}-impl-{implementation}）
在配置文件中定义可用实现
实现统一接口层

12.3 切换开源实现

修改 .trae/config.yml 中的 active 配置
安装必要的依赖
验证配置正确性

附录：常用忽略规则汇总

Java 项目

# Compiled class files
*.class

# Package files
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar

# Maven
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties
dependency-reduced-pom.xml
buildNumber.properties
.mvn/timing.properties
.mvn/wrapper/maven-wrapper.jar

# IDE
.idea/
*.iws
*.iml
*.ipr
.vscode/

JavaScript/TypeScript 项目

# Dependencies
node_modules/

# Build outputs
dist/
build/
.next/
.nuxt/

# TypeScript
*.tsbuildinfo
*.log

# IDE
.vscode/
.idea/

# Environment
.env
.env.local
.env.*.local

AI/ML 项目

# Model files
*.pt
*.pth
*.onnx
*.h5
*.bin
*.ckpt
*.joblib
*.pickle

# Datasets
data/
dataset/
datasets/

# Vector databases
chroma/
pinecone/
qdrant/

# Cache
.cache/
__pycache__/
.huggingface/
.tensorflow/

name	common-project-standard
description	项目规范技能，提供项目结构、文档管理、代码忽略等方面的标准和最佳实践
trigger	需要创建新项目或规范现有项目时
disable-when	项目已有完善的规范体系
category	common
tags	["project","standard","best-practices"]

项目规范技能

功能描述

提供项目结构、文档管理、代码忽略等方面的标准和最佳实践，帮助团队建立统一的项目规范。同时提供技能规范验证工具和开源技能包装机制。

何时使用

在以下情况调用此技能：

创建新项目时
维护现有项目时
需要制定项目规范时
需要验证技能规范性时
需要集成开源技能时

核心功能

技能管理：规范技能的创建和管理流程
文档管理：规范文档的编写和维护标准
Git忽略：规范 .gitignore 文件的配置
AI忽略：规范 AI 相关文件的忽略规则
项目结构：规范项目目录结构
技能安装：提供技能安装和配置指导
规范验证：验证技能是否符合标准格式
开源集成：支持开源技能的包装和切换

输入参数

参数	类型	必填	说明
projectType	String	否	项目类型（backend/frontend/fullstack）
framework	String	否	使用的框架
validateSkills	Boolean	否	是否验证技能规范
openSourceSkills	List	否	要集成的开源技能列表

输出格式

{
  "status": "SUCCESS",
  "projectType": "backend",
  "framework": "Spring Boot",
  "guidelines": {
    "skill": {...},
    "documentation": {...},
    "gitignore": {...},
    "aiIgnore": {...},
    "structure": {...},
    "installation": {...},
    "validation": {...},
    "openSourceIntegration": {...}
  }
}

1. 技能管理规范

1.1 技能目录结构

skills/
├── skill-name/           # 技能名称（小写连字符）
│   └── SKILL.md          # 技能定义文件（必填）

1.2 技能命名规范

类型	前缀	示例
异常分析	`exception-`	`exception-analysis`
AI 聊天	`spring-ai-`	`spring-ai-chat`
研发流程	`common-`	`common-coding`, `common-test`
个人技能	`personal-`	`personal-backend-coding-standard`
项目规范	`common-project-`	`common-project-standard`
开源包装	`os-`	`os-ui-library`, `os-chat-model`

1.3 SKILL.md 文档结构

---
name: "skill-name"
description: "技能描述，简要说明技能的核心价值和用途"
trigger: "触发条件，简洁描述技能何时被触发"
disable-when: "禁用条件，描述不适合使用此技能的场景"
category: "技能分类，如：backend/frontend/database/devops/ai"
tags: ["标签1", "标签2"]
requires: ["依赖技能1", "依赖技能2"]
---

# 技能名称

## 功能描述
## 触发条件
## 何时使用
## 何时不使用
## 核心功能
## 输入参数
## 输出格式
## 使用流程
## 调用示例
## 失败案例
## 最佳实践
## 配置要求
## 扩展指南

1.3.0 Frontmatter 元数据规范

Frontmatter 是技能的元数据定义区，用于描述技能的基本信息和属性：

字段	类型	必要性	说明
name	String	必填	技能名称，必须与目录名一致
description	String	必填	技能的核心价值和用途描述（1-2句话）
trigger	String	必填	触发条件，简洁描述技能何时被触发
disable-when	String	必填	禁用条件，描述不适合使用此技能的场景
category	String	必填	技能分类（backend/frontend/database/devops/ai等）
tags	Array	推荐	技能标签，用于分类和搜索
requires	Array	可选	依赖的其他技能名称

Frontmatter 示例：

---
name: "common-spring-boot-init"
description: "快速创建 Spring Boot 项目结构，支持多种数据库和依赖配置"
trigger: "用户请求创建新的 Spring Boot 项目时"
disable-when: "项目已存在或非 Java 技术栈项目"
category: "backend"
tags: ["spring", "java", "backend", "project-init"]
requires: ["common-db-design"]
---

1.3.1 文档章节说明

章节	必要性	说明
功能描述	必填	技能的核心能力和价值定位
触发条件	必填	技能被触发执行的条件和前置要求
何时使用	必填	适合使用此技能的场景
何时不使用	推荐	不适合使用此技能的场景（禁用样例）
核心功能	必填	技能提供的具体功能列表
输入参数	必填	输入参数定义（表格形式）
输出格式	必填	输出数据格式（JSON示例）
使用流程	推荐	使用该技能的步骤说明
调用示例	推荐	实际使用的代码或命令示例
失败案例	推荐	常见错误场景及解决方案
最佳实践	推荐	使用该技能的最佳实践建议
配置要求	可选	环境变量、配置文件等要求
扩展指南	可选	如何扩展或定制该技能

1.3.2 触发条件规范

触发条件应明确以下内容：

前置条件：使用技能前必须满足的条件
环境要求：所需的软件、依赖、权限等
数据准备：需要预先准备的数据或配置
触发方式：技能被调用的方式（API、命令行、事件等）

示例格式：

## 触发条件

- **前置条件**：项目已初始化，具备基础目录结构
- **环境要求**：Java 21+, Maven 3.8+, Spring Boot 3.2+
- **数据准备**：配置文件 `application.yml` 已存在
- **触发方式**：API 调用 / 命令行执行 / 事件触发

1.3.3 何时不使用（禁用样例）

明确列出不适合使用此技能的场景：

示例格式：

## 何时不使用

- 当项目已使用其他 ORM 框架时，不建议使用此技能
- 简单的 CRUD 操作无需使用此技能
- 需要复杂事务管理的场景请使用其他方案

1.3.4 失败案例规范

记录常见的失败场景及解决方案：

示例格式：

## 失败案例

| 错误场景 | 错误信息 | 解决方案 |
|----------|----------|----------|
| 数据库连接失败 | `Connection refused` | 检查数据库服务是否启动 |
| 权限不足 | `Permission denied` | 确认用户有足够的文件权限 |
| 依赖缺失 | `ClassNotFoundException` | 检查 pom.xml 依赖配置 |

1.4 技能注册流程

在 skills/ 目录下创建技能目录
创建 SKILL.md 文件
在 AGENTS.md 中添加技能说明
在 SKILLS.md 中注册技能

2. 文档管理规范

2.1 文档目录结构

docs/
├── api/                  # API 文档
│   └── openapi.yaml
├── architecture/         # 架构文档
│   └── architecture.md
├── guides/               # 使用指南
│   └── getting-started.md
├── README.md             # 项目说明（根目录）
├── AGENTS.md             # 代理与技能架构（根目录）
└── SKILLS.md             # 技能清单（根目录）

2.2 文档命名规范

类型	命名规则	示例
文档文件	小写连字符	`getting-started.md`
目录名称	小写连字符	`api/`, `guides/`

2.3 文档模板

README.md 模板

# 项目名称

## 项目简介
## 技术栈
## 快速开始
## 项目结构
## API 接口
## 开发指南
## 部署说明
## 贡献指南
## 许可证

SKILLS.md 模板

# 技能清单

## 个人定制技能

| 技能名称 | 描述 |
|----------|------|
| personal-backend-coding-standard | 后端编码规范技能 |
| personal-frontend-coding-standard | 前端编码规范技能 |

## 通用技能

| 技能名称 | 描述 |
|----------|------|
| common-project-standard | 项目规范技能 |
| common-contract-generation | 契约生成技能 |
| common-frontend-playwright-test | 前端Playwright测试技能 |
| common-backend-unit-test | 后端单元测试技能 |
| common-coding | 编码技能 |
| common-requirement-clarification | 需求澄清技能 |

## 功能技能

| 技能名称 | 描述 |
|----------|------|
| spring-ai-chat | Spring AI 聊天集成 |
| model-provider-creator | 模型提供商创建器 |
| mcp-tool-creator | MCP工具创建器 |
| plan-executor | 计划执行器 |
| exception-analysis | 异常分析技能 |

## 开源技能包装

| 技能名称 | 描述 | 底层实现 |
|----------|------|----------|
| os-ui-library | UI组件库技能 | 可配置（自研/Component-A/Component-B） |
| os-chat-model | 聊天模型技能 | 可配置（OpenAI/DeepSeek/Claude） |

AGENTS.md 模板

# 代理与技能架构

## 概述

本项目使用 Trae AI 技能系统，通过技能扩展项目能力。

## 技能目录

所有技能位于 `skills/` 目录下。

## 技能分类

### 个人定制技能
- personal-backend-coding-standard - 后端编码规范
- personal-frontend-coding-standard - 前端编码规范

### 通用技能
- common-project-standard - 项目规范
- common-contract-generation - 契约生成
- common-frontend-playwright-test - 前端测试
- common-backend-unit-test - 后端测试
- common-coding - 编码规范
- common-requirement-clarification - 需求澄清

### 功能技能
- spring-ai-chat - AI 聊天功能
- model-provider-creator - 模型提供商
- mcp-tool-creator - MCP工具创建
- plan-executor - 计划执行器
- exception-analysis - 异常分析

### 开源技能包装
- os-ui-library - UI组件库（可切换实现）
- os-chat-model - 聊天模型（可切换实现）

## 技能使用方式

### 1. 安装技能

使用项目根目录的 `install-skills.sh` 脚本安装技能：

```bash
# 安装所有技能
./install-skills.sh /path/to/project

# 安装指定技能
./install-skills.sh -s common-coding -s common-project-standard .

2. 注册技能

在 SKILLS.md 中注册技能，系统会自动加载。

3. 使用技能

在需要时调用相应的技能接口。

4. 验证技能规范

# 验证所有技能
./validate-skills.sh

# 验证指定技能
./validate-skills.sh -s common-coding

# 修复技能格式
./validate-skills.sh -f


### 2.4 文档编写规范

1. **语言**：统一使用中文
2. **格式**：使用 Markdown 格式
3. **标题**：使用 `#` 表示标题层级
4. **代码块**：使用三个反引号 + 语言标识
5. **链接**：使用绝对路径或相对路径

---

## 3. Git 忽略规范

### 3.1 .gitignore 文件位置

- 根目录：`.gitignore` - 全局忽略规则
- 模块目录：`module/.gitignore` - 模块特定规则

### 3.2 通用忽略规则

```gitignore
# 构建产物
target/
build/
dist/
*.class
*.jar
*.war

# IDE 文件
.idea/
.vscode/
.project
.classpath
.settings/

# 日志文件
*.log
logs/

# 配置文件
application-local.yml
application-local.properties
.env

# OS 文件
.DS_Store
Thumbs.db

# Maven
.mvn/
mvnw
mvnw.cmd

# Gradle
.gradle/
gradlew
gradlew.bat

3.3 后端项目忽略规则

# 数据库文件
*.db
*.sqlite

# JVM 相关
hs_err_pid*
replay_pid*

# Spring Boot
spring-shell.log

3.4 前端项目忽略规则

# Node.js
node_modules/
package-lock.json
yarn.lock

# 构建工具
.next/
.nuxt/
.svelte-kit/

# TypeScript
*.tsbuildinfo

4. AI 忽略规范

4.1 AI 相关文件识别

类型	描述	示例
模型文件	训练好的 AI 模型	`model.pt`, `model.onnx`
数据集	训练数据	`data/`, `dataset/`
缓存文件	AI 工具生成的缓存	`.cache/`, `__pycache__/`
向量数据库	向量索引文件	`chroma/`, `pinecone/`

4.2 AI 忽略规则

# AI 模型文件
*.pt
*.pth
*.onnx
*.h5
*.bin
*.ckpt

# 数据集
data/
dataset/
datasets/

# 向量数据库
chroma/
pinecone/
qdrant/
weaviate/

# 缓存目录
.cache/
__pycache__/
.huggingface/
.tensorflow/

# 模型下载目录
models/
downloads/
checkpoints/

4.3 AI 配置文件管理

# API Key 文件
*.key
*.secret
api-keys.json

# 配置文件
config/secrets.yml
config/secrets.json

# 环境变量
.env.local
.env.production

5. Trae 忽略规范

5.1 .traeignore 文件位置

根目录：.traeignore - 全局 Trae 忽略规则

5.2 .traeignore 作用

.traeignore 文件用于指定 Trae AI 系统应忽略的文件和目录，这些文件不会被技能系统加载或处理。

5.3 .traeignore 标准配置

# 技能缓存目录
.cache/
.skills-cache/

# 技能临时文件
*.tmp
*.temp

# 技能索引文件
skills-index.json
skills-mapping.json

# 日志文件
*.log
logs/

# 测试文件
__tests__/
*.test.js
*.spec.js

# 编辑器文件
.vscode/
.idea/
*.swp
*.swo
*~

# 系统文件
.DS_Store
Thumbs.db

# 技能开发文件
dev/
examples/
samples/

# 技能模板文件
*.template
*.stub

# 技能打包文件
*.zip
*.tar.gz
*.tgz

# 依赖目录
node_modules/
vendor/

# 构建产物
dist/
build/

5.4 .traeignore 与 .gitignore 的区别

文件	作用	适用范围
`.gitignore`	版本控制忽略	Git 仓库
`.traeignore`	技能系统忽略	Trae AI 技能加载

5.5 联合使用建议

项目根目录
├── .gitignore          # Git 版本控制忽略
├── .traeignore         # Trae 技能系统忽略
└── .trae/
    ├── skills/         # 技能目录（Git 追踪，Trae 加载）
    └── cache/          # 缓存目录（Git 忽略，Trae 忽略）

5.6 示例配置

项目根目录 .gitignore：

# Trae 缓存目录
.trae/cache/
.trae/.cache/

# Trae 临时文件
.trae/*.tmp

项目根目录 .traeignore：

# 忽略技能开发目录
dev/
examples/

# 忽略测试文件
__tests__/
*.test.js

# 忽略编辑器配置
.vscode/
.idea/

技能目录 .traeignore（可选）：

# 技能内部忽略规则
node_modules/
*.log

6. 项目结构规范

6.1 后端项目结构

xx-parent/                     # Maven 父模块
├── pom.xml                    # 父 POM 配置
├── xx-gateway/               # 网关模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/gateway/
│       └── resources/
├── xx-biz/                   # 业务模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/biz/
│       └── resources/
├── xx-infra/                 # 基础设施模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/infra/
│       └── resources/
└── .trae/                    # 技能目录
    └── skills/

6.2 模块职责说明

模块	职责	说明
`xx-gateway`	请求路由和认证	处理外部请求，进行认证授权
`xx-biz`	核心业务逻辑	实现业务功能，处理业务规则
`xx-infra`	基础设施支持	公共组件、工具类、配置

6.3 包结构规范

com/bage/xx/
├── controller/          # REST API 控制层
├── service/             # 业务逻辑层
│   └── impl/           # 服务实现
├── repository/          # 数据访问层
├── entity/              # 数据库实体
├── dto/                 # 数据传输对象
│   ├── request/        # 请求 DTO
│   └── response/       # 响应 DTO
├── config/              # 配置类
├── exception/           # 自定义异常
└── util/                # 工具类

7. 技能安装与配置

7.1 安装方式

使用安装脚本（推荐）

# 从 skills 仓库安装到目标项目
bash <(curl -s https://raw.githubusercontent.com/your-repo/study-ai-skills/main/install-skills.sh) /path/to/your/project

# 或者克隆仓库后安装
git clone https://github.com/your-repo/study-ai-skills.git
cd study-ai-skills
./install-skills.sh /path/to/your/project

手动安装

# 创建技能目录
mkdir -p /path/to/your/project/.trae/skills

# 复制技能（以 common-project-standard 为例）
cp -r /path/to/study-ai-skills/skills/common-project-standard /path/to/your/project/skills/

7.2 安装脚本使用说明

# 查看帮助
./install-skills.sh -h

# 列出所有可用技能
./install-skills.sh -l

# 安装所有技能到当前目录
./install-skills.sh .

# 安装所有技能到指定目录
./install-skills.sh /path/to/project

# 安装指定技能
./install-skills.sh -s common-coding -s personal-backend-coding-standard .

# 强制覆盖已存在的技能
./install-skills.sh -f -s common-project-standard .

# 交互式安装
./install-skills.sh -i

# 指定IDE安装
./install-skills.sh --ide trae .

7.3 配置文件

创建 .trae/config.yml 配置文件：

# .trae/config.yml
skills:
  # 是否自动加载所有技能
  auto-load: true
  
  # 技能搜索路径
  paths:
    - .trae/skills
  
  # 默认启用的技能
  enabled:
    - personal-backend-coding-standard
    - personal-frontend-coding-standard
    - common-project-standard
    - common-coding
    - common-contract-generation
    - common-backend-unit-test
    - common-frontend-playwright-test
    - common-requirement-clarification
    - spring-ai-chat
    - model-provider-creator
    - mcp-tool-creator
    - plan-executor
    - exception-analysis

6.4 全局配置（推荐）

在用户主目录创建配置文件，使所有项目默认使用这些技能：

# 创建全局配置目录
mkdir -p ~/.trae

# 创建全局技能配置
cat > ~/.trae/skills-config.yml << 'EOF'
# 全局技能配置
skills:
  # 技能仓库位置
  repository: ~/bage/github/study/study-ai-skills/.trae/skills
  
  # 默认启用的技能
  default-enabled:
    - personal-backend-coding-standard
    - personal-frontend-coding-standard
    - common-project-standard
    - common-coding
  
  # 自动同步更新
  auto-sync: true
EOF

# 创建全局安装脚本链接
ln -sf ~/bage/github/study/study-ai-skills/install-skills.sh ~/.trae/install-skills.sh

# 添加到 PATH
echo 'export PATH="$HOME/.trae:$PATH"' >> ~/.bashrc
echo 'export PATH="$HOME/.trae:$PATH"' >> ~/.zshrc

8. 技能规范验证

8.1 验证脚本使用

# 验证所有技能
./validate-skills.sh

# 验证指定技能
./validate-skills.sh -s common-coding

# 列出所有技能
./validate-skills.sh -l

# 修复技能格式
./validate-skills.sh -f

# 修复指定技能
./validate-skills.sh -f -s common-coding

8.2 验证规则

检查项	说明	级别
SKILL.md 存在	技能目录必须包含 SKILL.md	错误
Frontmatter 完整	必须包含 name 和 description 字段	错误
name 匹配目录名	name 字段值应与目录名一致	警告
功能描述章节	必须包含 ## 功能描述	警告
何时使用章节	必须包含 ## 何时使用	警告
核心功能章节	必须包含 ## 核心功能	警告
输入参数章节	必须包含 ## 输入参数	警告
输出格式章节	必须包含 ## 输出格式	警告
输入参数表格	输入参数章节应包含表格	警告
输出格式示例	输出格式章节应包含示例	警告

8.3 修复功能

验证脚本的 -f 参数可以自动修复以下问题：

创建缺失的 SKILL.md 文件
添加缺失的 Frontmatter 字段
添加缺失的章节标题

9. 开源技能包装机制

9.1 设计理念

为了支持多种实现的切换，开源技能采用包装模式：

┌─────────────────────────────────────────────────────┐
│                    技能接口层                       │
│              (Skill Interface)                      │
│  ┌─────────────────────────────────────────────┐   │
│  │  - 统一的输入参数                            │   │
│  │  - 统一的输出格式                            │   │
│  │  - 统一的调用方式                            │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│                    实现切换层                       │
│              (Implementation Switch)               │
│  ┌─────────────────────────────────────────────┐   │
│  │  - 配置驱动的实现选择                         │   │
│  │  - 运行时动态切换                           │   │
│  │  - 实现隔离与解耦                           │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│  自研实现     │ │ 开源实现 A    │ │ 开源实现 B    │
│ (Default)    │ │ (OpenSourceA) │ │ (OpenSourceB) │
└───────────────┘ └───────────────┘ └───────────────┘

9.2 技能命名约定

前缀	说明	示例
`os-`	开源技能包装	`os-ui-library`, `os-chat-model`
`os-{name}-impl-`	具体实现	`os-ui-library-impl-native`, `os-ui-library-impl-componenta`

9.3 配置方式

# .trae/config.yml
skills:
  open-source:
    # UI组件库实现选择: native/componenta/componentb
    os-ui-library:
      active: native
      implementations:
        - name: native
          description: 自研轻量级实现
          enabled: true
        - name: componenta
          description: 基于 Component Library A
          enabled: true
          dependencies:
            - "@componenta/core"
        - name: componentb
          description: 基于 Component Library B
          enabled: false
          dependencies:
            - "@componentb/react"
    
    # 聊天模型实现选择: openai/deepseek/claude
    os-chat-model:
      active: deepseek
      implementations:
        - name: openai
          description: OpenAI API
          enabled: true
          env:
            - OPENAI_API_KEY
        - name: deepseek
          description: DeepSeek API
          enabled: true
          env:
            - DEEPSEEK_API_KEY
        - name: claude
          description: Claude API
          enabled: true
          env:
            - CLAUDE_API_KEY

9.4 开源技能包装示例

技能目录结构

skills/
├── os-ui-library/                    # 包装技能（统一接口）
│   └── SKILL.md
├── os-ui-library-impl-native/        # 自研实现
│   └── SKILL.md
├── os-ui-library-impl-componenta/    # 组件库A实现
│   └── SKILL.md
└── os-ui-library-impl-componentb/    # 组件库B实现
    └── SKILL.md

SKILL.md 包装层示例

---
name: "os-ui-library"
description: "UI组件库技能 - 支持多种实现切换"
---

# UI组件库技能

## 功能描述

提供统一的 UI 组件库接口，支持多种实现切换。

## 何时使用

需要使用 UI 组件时，通过配置选择不同实现。

## 核心功能

- 统一的组件接口
- 运行时实现切换
- 多种开源组件库支持

## 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| componentType | String | 是 | 组件类型 |
| props | Object | 否 | 组件属性 |
| implementation | String | 否 | 指定实现（native/componenta/componentb） |

## 输出格式

```json
{
  "status": "SUCCESS",
  "implementation": "native",
  "component": {...}
}

实现配置

在 .trae/config.yml 中配置：

skills:
  open-source:
    os-ui-library:
      active: native

可用实现

实现名称	描述	状态
native	自研轻量级实现	✅
componenta	基于 Component Library A	✅
componentb	基于 Component Library B	⚠️


### 9.5 切换实现流程

```bash
# 查看当前配置
cat .trae/config.yml | grep -A 5 "os-ui-library"

# 切换到 Component Library A
sed -i '' 's/active: native/active: componenta/' .trae/config.yml

# 安装依赖（如果需要）
npm install @componenta/core

# 验证切换
./validate-skills.sh -s os-ui-library

10. 代码审查检查清单

检查项	说明	状态
技能结构	技能目录和文件是否符合规范	✅/❌
文档完整性	是否有必要的文档说明	✅/❌
Git忽略	.gitignore 是否完整	✅/❌
AI忽略	AI 相关文件是否正确忽略	✅/❌
Trae忽略	.traeignore 是否完整	✅/❌
项目结构	目录结构是否符合规范	✅/❌
命名规范	文件和目录命名是否符合规范	✅/❌
技能注册	是否在 SKILLS.md 中注册	✅/❌
规范验证	是否通过技能规范验证	✅/❌
开源包装	开源技能是否符合包装规范	✅/❌

11. 配置要求

11.1 环境变量

变量名	说明	默认值
PROJECT_NAME	项目名称	-
PROJECT_TYPE	项目类型	backend
TRAE_SKILLS_PATH	技能目录路径	.trae/skills

11.2 配置文件

project:
  name: xx
  type: backend
  modules:
    - gateway
    - biz
    - infra

skills:
  auto-load: true
  paths:
    - .trae/skills
  open-source:
    os-ui-library:
      active: native
    os-chat-model:
      active: deepseek

12. 扩展指南

12.1 添加新技能

在 skills/ 目录下创建新目录
创建 SKILL.md 文件
在 AGENTS.md 中注册技能
在 SKILLS.md 中添加技能清单
使用 ./validate-skills.sh 验证格式

12.2 添加开源技能包装

创建包装层技能（os-{name}）
创建各实现技能（os-{name}-impl-{implementation}）
在配置文件中定义可用实现
实现统一接口层

12.3 切换开源实现

修改 .trae/config.yml 中的 active 配置
安装必要的依赖
验证配置正确性

附录：常用忽略规则汇总

Java 项目

# Compiled class files
*.class

# Package files
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar

# Maven
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties
dependency-reduced-pom.xml
buildNumber.properties
.mvn/timing.properties
.mvn/wrapper/maven-wrapper.jar

# IDE
.idea/
*.iws
*.iml
*.ipr
.vscode/

JavaScript/TypeScript 项目

# Dependencies
node_modules/

# Build outputs
dist/
build/
.next/
.nuxt/

# TypeScript
*.tsbuildinfo
*.log

# IDE
.vscode/
.idea/

# Environment
.env
.env.local
.env.*.local

AI/ML 项目

# Model files
*.pt
*.pth
*.onnx
*.h5
*.bin
*.ckpt
*.joblib
*.pickle

# Datasets
data/
dataset/
datasets/

# Vector databases
chroma/
pinecone/
qdrant/

# Cache
.cache/
__pycache__/
.huggingface/
.tensorflow/

common-project-standard

More from this repository

More from this repository

项目规范技能

功能描述

何时使用

核心功能

输入参数

输出格式

1. 技能管理规范

1.1 技能目录结构

1.2 技能命名规范

1.3 SKILL.md 文档结构

1.3.0 Frontmatter 元数据规范

1.3.1 文档章节说明

1.3.2 触发条件规范

1.3.3 何时不使用（禁用样例）

1.3.4 失败案例规范

1.4 技能注册流程

2. 文档管理规范

2.1 文档目录结构

2.2 文档命名规范

2.3 文档模板

README.md 模板

SKILLS.md 模板

AGENTS.md 模板

2. 注册技能

3. 使用技能

4. 验证技能规范

3.3 后端项目忽略规则

3.4 前端项目忽略规则

4. AI 忽略规范

4.1 AI 相关文件识别

4.2 AI 忽略规则

4.3 AI 配置文件管理

5. Trae 忽略规范

5.1 .traeignore 文件位置

5.2 .traeignore 作用

5.3 .traeignore 标准配置

5.4 .traeignore 与 .gitignore 的区别

5.5 联合使用建议

5.6 示例配置

6. 项目结构规范

6.1 后端项目结构

6.2 模块职责说明

6.3 包结构规范

7. 技能安装与配置

7.1 安装方式

使用安装脚本（推荐）

手动安装

7.2 安装脚本使用说明

7.3 配置文件

6.4 全局配置（推荐）

8. 技能规范验证

8.1 验证脚本使用

8.2 验证规则

8.3 修复功能

9. 开源技能包装机制

9.1 设计理念

9.2 技能命名约定

9.3 配置方式

9.4 开源技能包装示例

技能目录结构

SKILL.md 包装层示例

实现配置

可用实现

10. 代码审查检查清单

11. 配置要求

11.1 环境变量

11.2 配置文件

12. 扩展指南

12.1 添加新技能

12.2 添加开源技能包装

12.3 切换开源实现

附录：常用忽略规则汇总

Java 项目

JavaScript/TypeScript 项目

AI/ML 项目

项目规范技能

功能描述