# skill.yaml 规范文档

## 概述

`skill.yaml` 是技能的元数据定义文件，位于技能仓库根目录。

## 字段定义

### 必填字段

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `name` | string | hyphen-case, ≤64字符 | 技能唯一标识 |
| `version` | string | 语义化版本 | 当前版本号 |
| `description` | string | ≤1024字符 | 技能描述 |

### 可选字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `author` | string | - | 作者/团队 |
| `license` | string | - | 许可证 |
| `triggers` | object | - | 触发条件 |
| `prompt_file` | string | SKILL.md | 提示词文件 |
| `dependencies` | array | [] | 依赖技能列表 |
| `mcp_servers` | array | [] | MCP 服务器依赖 |
| `hooks` | object | - | 生命周期钩子 |
| `allowed_tools` | array | - | 允许的工具 |
| `metadata` | object | - | 自定义元数据 |

## triggers 结构

```yaml
triggers:
  # 关键词触发 - 用户输入包含这些词时激活
  keywords:
    - coolbuy-paas
    - 酷采

  # 命令触发 - 用户输入以这些命令开头时激活
  commands:
    - /skill

  # 文件模式触发 - 当前目录匹配时激活
  file_patterns:
    - "**/coolbuy-paas/**"
```

## hooks 结构

```yaml
hooks:
  # 安装后执行
  post_install:
    - "echo 'Installed'"
    - "npm install"

  # 更新后执行
  post_update:
    - "echo 'Updated'"

  # 卸载前执行
  post_uninstall:
    - "echo 'Goodbye'"
```

## 完整示例

```yaml
name: coolbuy-paas
version: 1.2.0
description: |
  酷采3.0 SaaS 租户端开发与测试。
  支持商品管理、订单管理等模块开发。
author: your-team
license: MIT

triggers:
  keywords:
    - coolbuy-paas
    - 酷采
    - 商品管理
    - 租户端
  file_patterns:
    - "**/coolbuy-paas/**"

prompt_file: SKILL.md

dependencies:
  - dev-coding
  - ops-tools

mcp_servers:
  - ai-proj
  - chrome-devtools

hooks:
  post_install:
    - "echo '✓ coolbuy-paas 技能安装完成'"
  post_update:
    - "echo '✓ coolbuy-paas 技能已更新'"

allowed_tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep

metadata:
  category: business
  tags:
    - saas
    - ecommerce
    - tenant
  min_claude_version: "1.0.0"
  project_repo: "https://github.com/org/coolbuy-paas"
```

## 验证规则

1. **name**:
   - 只能包含小写字母、数字、连字符
   - 不能以连字符开头或结尾
   - 长度 1-64 字符

2. **version**:
   - 符合语义化版本规范 (SemVer)
   - 格式: MAJOR.MINOR.PATCH

3. **description**:
   - 长度不超过 1024 字符
   - 不能包含 `<` 或 `>` 字符

4. **prompt_file**:
   - 文件必须存在
   - 必须是 Markdown 格式

5. **dependencies**:
   - 每个依赖必须是有效的技能名称
   - 不能有循环依赖

## 与 Anthropic 官方规范对比

| 字段 | 官方规范 | 本规范 | 说明 |
|------|----------|--------|------|
| name | ✓ | ✓ | 相同 |
| description | ✓ | ✓ | 相同 |
| license | ✓ | ✓ | 相同 |
| allowed-tools | ✓ | allowed_tools | 命名调整 |
| metadata | ✓ | ✓ | 相同 |
| version | ✗ | ✓ | 新增 |
| triggers | ✗ | ✓ | 新增 |
| dependencies | ✗ | ✓ | 新增 |
| hooks | ✗ | ✓ | 新增 |
| mcp_servers | ✗ | ✓ | 新增 |