skill-writer

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Skill Writer - 技能编写指南
## Overview
本技能提供**标准技能文件格式模板**和**编写规范**，帮助开发者正确创建新的技能文件，避免格式错误导致系统无法加载。
**核心用途**：
- 提供标准 YAML Front Matter 格式
- 提供技能文件结构模板
- 提供常见格式错误检查清单
- 提供技能最佳实践指南
---
## Routing Table
| 关键词 | 描述 |
|--------|------|
| `创建技能`, `新建技能`, `写技能` | 创建新技能文件 |
| `技能模板`, `skill template` | 获取标准技能模板 |
| `技能格式`, `skill format` | 检查技能格式是否正确 |
| `YAML front matter` | 获取 YAML 头部格式规范 |
| `技能目录结构` | 获取技能文件夹结构要求 |
| `全局技能`, `项目技能` | 创建技能前确认技能作用域并选择正确目录 |
| `格式错误`, `加载失败` | 诊断技能格式问题 |
---
## Scope
本技能涵盖以下功能：

1. **标准模板提供** - 完整的 SKILL.md 文件模板
2. **YAML 格式规范** - 正确的 YAML Front Matter 写法
3. **目录结构规范** - 技能文件夹的标准结构
4. **格式检查清单** - 验证技能格式是否正确
5. **常见错误示例** - 展示常见格式错误及修正方法
6. **最佳实践指南** - 技能编写的最佳实践
7. **示例参考** - 提供多个技能的参考示例
8. **自动修复建议** - 针对格式错误提供修复方案
9. **技能作用域选择** - 创建技能前必须确认创建全局技能还是项目技能
10. **技能目录获取** - 创建技能前必须调用目录工具获取全局技能目录和工作目录技能目录
---
## Out of Scope
以下功能**不在**本技能范围内：

1. ? 技能业务逻辑设计（应使用对应领域技能）
2. ? 技能资源文件内容编写
3. ? 技能脚本代码编写
4. ? 技能测试和调试
5. ? 技能发布和部署流程
6. ? 技能性能优化
7. ? 技能版本管理策略
---
## Standard Template (标准模板)
### 完整 SKILL.md 文件模板
```markdown
---
name: skill-name
description: Brief description of what this skill does
license: MIT
user-invocable: true
---
# Skill Title
## Overview
Brief overview of the skill's purpose and capabilities.
## Routing Table
| Keyword | Description |
|---------|-------------|
| `keyword1` | What it triggers |
| `keyword2` | What it triggers |
## Scope
List of capabilities covered by this skill:
1. Capability 1
2. Capability 2
3. Capability 3
## Out of Scope
List of capabilities NOT covered:
1. ? Not covered 1
2. ? Not covered 2
## Usage Examples
### Example 1: Basic Usage
Description of the example.
### Example 2: Advanced Usage
Description of the advanced example.
## Resources
- `resource-name` - Description of the resource
## Scripts
- `script-name.ps1` - Description of the script
```
---
## YAML Front Matter 规范
### 必需字段
```yaml
---
name: skill-name              # 必需：技能名称（英文，小写，连字符分隔）
description: Description      # 必需：简短描述（英文）
license: MIT                  # 必需：许可证类型
user-invocable: true          # 必需：是否允许用户调用（true/false）
---
```
### 字段要求
| 字段 | 类型 | 要求 | 示例 |
|------|------|------|------|
| `name` | string | 必需，英文小写，连字符分隔 | `skill-writer`, `dotnet-api` |
| `description` | string | 必需，英文简短描述 | `Skill creation template` |
| `license` | string | 必需，通常 MIT | `MIT`, `Apache-2.0` |
| `user-invocable` | boolean | 必需，true 或 false（小写） | `true`, `false` |
### 常见错误
| 错误写法 | 正确写法 | 说明 |
|----------|----------|------|
| `name: Skill-Name` | `name: skill-name` | 必须小写 |
| `user-invocable: True` | `user-invocable: true` | 布尔值必须小写 |
| 没有 `---` 分隔符 | 必须有 `---` 包裹 | YAML 必须用三横线包裹 |
| YAML 不在文件第一行 | YAML 必须在开头 | 前面不能有空行或内容 |
---
## Directory Structure (目录结构)
### 创建位置选择
当用户要求创建技能时，必须先询问用户要创建哪一种技能：

1. **全局技能** - 适用于所有工作区，必须放在全局技能目录下。
2. **项目技能** - 仅适用于当前工作区，必须放在工作目录技能目录下。

创建技能前必须调用以下工具获取实际目录，不要手写或猜测路径：

| 技能类型 | 必须调用的工具 | 目录用途 |
|----------|----------------|----------|
| 项目技能 | `sys_get_workspace_skills_directory` | 获取当前工作目录技能目录 |
| 全局技能 | `sys_get_user_skills_directory` | 获取当前用户全局技能目录 |

From sunyonghuan/Netor.Madorin, MIT.

More from sunyonghuan/Netor.Madorin