# skills

**Repository Path**: handuan-cloud/skills

## Basic Information

- **Project Name**: skills
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Skills Repository

本仓库用于存储和管理可被 openskills 工具加载的技能定义，支持命名空间组织和规范化命名，便于团队协作和技能复用。

## 仓库结构

```
skills-repository/
├── README.md                    # 本文档
├── .gitignore                   # Git 忽略规则
└── skills/                      # 技能根目录
    ├── smeco/                   # smeco 命名空间
    │   └── frontend-base/       # 前端基础技能
    ├── common/                  # 通用命名空间（示例）
    └── [other-namespaces]/      # 其他命名空间
```

### 目录说明

- **skills/**: 所有技能的根容器目录
- **命名空间目录**: 用于组织和分类技能（如 `smeco`、`common` 等）
- **技能目录**: 包含单个技能的所有定义和资源

## 命名规范

### 命名空间和技能名称规范

命名空间和技能名称必须遵循以下规则：

- **仅使用小写字母**（a-z）
- **可使用数字**（0-9）
- **使用连字符**（-）分隔单词
- **不能以连字符开头或结尾**
- **不能包含连续的连字符**

**格式**: `[a-z0-9]+(-[a-z0-9]+)*`

#### 有效示例

```
✓ smeco
✓ common
✓ team-alpha
✓ project-2024
✓ frontend-base
✓ api-design-patterns
```

#### 无效示例

```
✗ Smeco           (包含大写字母)
✗ team_alpha      (使用下划线)
✗ -team           (以连字符开头)
✗ team-           (以连字符结尾)
✗ team--alpha     (连续连字符)
✗ FrontendBase    (包含大写字母)
```

### 技能路径格式

技能通过路径引用，格式为：`namespace/skill-name`

**示例**:

- `smeco/frontend-base`
- `common/api-design`
- `team-alpha/testing-guide`

## 如何添加新技能

### 步骤 1: 创建或选择命名空间

如果需要新的命名空间，在 `skills/` 目录下创建命名空间目录：

```bash
mkdir skills/your-namespace
```

确保命名空间名称符合命名规范。

### 步骤 2: 创建技能目录

在命名空间下创建技能目录：

```bash
mkdir skills/your-namespace/your-skill-name
```

### 步骤 3: 创建技能定义文件

在技能目录中创建主要定义文件 `skill.md`：

```bash
touch skills/your-namespace/your-skill-name/skill.md
```

### 步骤 4: 编写技能内容

在 `skill.md` 中编写技能定义，建议包含以下内容：

```markdown
# 技能名称

## 概述

简要说明技能的用途和适用场景

## 技术栈

列出相关的技术、框架和工具

## 编码规范

详细的编码规范和最佳实践

## 示例代码

提供实用的代码示例

## 参考资源

相关文档和学习资源链接
```

### 步骤 5: 添加辅助资源（可选）

可以在技能目录中添加辅助文件和子目录：

```bash
mkdir skills/your-namespace/your-skill-name/examples
mkdir skills/your-namespace/your-skill-name/templates
```

### 完整示例

创建一个名为 `team-alpha/testing-guide` 的技能：

```bash
# 创建命名空间（如果不存在）
mkdir -p skills/team-alpha

# 创建技能目录
mkdir skills/team-alpha/testing-guide

# 创建定义文件
cat > skills/team-alpha/testing-guide/skill.md << 'EOF'
# Testing Guide

## 概述
本技能提供单元测试和集成测试的最佳实践指南。

## 技术栈
- Jest
- React Testing Library
- Cypress

## 编码规范
...
EOF

# 创建示例目录
mkdir skills/team-alpha/testing-guide/examples
```

## 使用 Openskills 工具

### 加载技能

使用技能路径加载技能：

```bash
# 加载 smeco/frontend-base 技能
openskills load smeco/frontend-base

# 加载 common/api-design 技能
openskills load common/api-design
```

### 列出可用技能

```bash
# 列出所有命名空间
openskills list-namespaces

# 列出特定命名空间下的技能
openskills list-skills smeco
```

### 查看技能信息

```bash
# 查看技能详细信息
openskills info smeco/frontend-base
```

## 技能目录结构

每个技能目录可以包含以下内容：

### 必需文件

- **skill.md** 或 **README.md**: 主要技能定义文件

### 可选内容

- **examples/**: 代码示例目录
- **templates/**: 模板文件目录
- 其他辅助文件和子目录

### 示例结构

```
skills/smeco/frontend-base/
├── skill.md              # 主要定义文件
├── examples/             # 代码示例
│   ├── component.vue
│   └── composable.ts
└── templates/            # 模板文件
    └── page-template.vue
```

## 设计原则

### 1. 单一职责

每个技能目录只包含一个技能的定义和资源。

### 2. 命名空间隔离

不同命名空间之间完全独立，互不影响。

### 3. 扁平化层级

仅使用两级目录结构（`namespace/skill-name`），避免过深嵌套。

### 4. 约定优于配置

通过目录结构和命名规范隐式定义技能路径。

### 5. 向后兼容

新增技能或命名空间不影响现有引用。

## 贡献指南

### 添加新技能

1. 确保技能名称符合命名规范
2. 在适当的命名空间下创建技能目录
3. 编写清晰、完整的技能定义
4. 提供实用的代码示例
5. 提交 Pull Request

### 更新现有技能

1. 保持技能路径不变
2. 更新技能定义内容
3. 添加或更新示例代码
4. 提交 Pull Request

### 代码审查要点

- 命名是否符合规范
- 技能定义是否清晰完整
- 示例代码是否实用
- 文档是否易于理解

## 常见问题

### Q: 如何选择命名空间？

A: 根据项目或团队进行分类。例如：

- 项目特定技能：使用项目名称（如 `smeco`）
- 通用技能：使用 `common` 命名空间
- 团队特定技能：使用团队名称（如 `team-alpha`）

### Q: 技能名称应该如何命名？

A: 使用描述性名称，清晰表达技能用途。例如：

- `frontend-base`: 前端基础技能
- `api-design-patterns`: API 设计模式
- `testing-guide`: 测试指南

### Q: 可以嵌套命名空间吗？

A: 不可以。仓库采用扁平化结构，仅支持一级命名空间。

### Q: 如何处理技能之间的依赖？

A: 在技能定义文件中说明依赖关系，并提供相关技能的路径引用。

## 许可证

[根据项目需要添加许可证信息]

## 联系方式

[根据项目需要添加联系方式]