````markdown
# CLI Agent Skill Design Guide

Version: 2.0

---

# 1. Design Philosophy

Skill 不是 Prompt。

Skill 应该被视为一个：

- 可发现（Discoverable）
- 可决策（Decidable）
- 可执行（Executable）
- 可验证（Verifiable）

的能力模块。

目标不是让 AI 看到更多内容。

目标是让 AI：

1. 知道什么时候使用
2. 知道什么时候不要使用
3. 知道如何执行
4. 知道如何验证结果

---

# 2. Core Principles

## Principle 1: Single Responsibility

一个 Skill 只负责一个目标。

### Good

github_issue_create

### Bad

github_assistant

原因：

职责越单一：

- 调用率越高
- 误调用越少
- 维护越容易

---

## Principle 2: Action-Oriented Naming

名称必须体现动作。

### Good

mysql_query_analyze

docker_container_debug

git_commit_generate

### Bad

mysql

docker

git

推荐格式：

<domain>_<action>

---

## Principle 3: Clear Boundaries

Skill 必须有明确边界。

AI 应该能够区分：

- 什么时候使用
- 什么时候不使用

否则容易误调用。

---

## Principle 4: Verifiable Results

每个 Skill 必须能够验证结果。

错误：

"执行完成"

正确：

"文件存在"

"PR 创建成功"

"返回 Issue URL"

---

# 3. Required Sections

每个 Skill 必须包含以下内容。

## Metadata

用于发现 Skill。

```yaml
name:
description:
tags:
````

---

## Use Cases

用于决策。

```yaml
when_to_use:
```

示例：

```yaml
when_to_use:
  - 用户反馈Bug
  - 用户希望创建Issue
  - 用户提出功能需求
```

---

## Exclusions

用于避免误调用。

```yaml
when_not_to_use:
```

示例：

```yaml
when_not_to_use:
  - 查询Issue
  - 创建PR
  - 修改代码
```

---

## Inputs

定义输入。

```yaml
inputs:
```

示例：

```yaml
repository:
  type: string
  required: true
  example: owner/repo
```

每个输入必须包含：

* type
* required
* description
* example

---

## Outputs

定义输出。

```yaml
outputs:
```

示例：

```yaml
issue_number:
  type: integer

issue_url:
  type: string
```

推荐：

* JSON
* YAML

禁止：

自然语言输出

---

## Workflow

定义执行流程。

示例：

1. 验证仓库存在

2. 检查重复 Issue

3. 创建 Issue

4. 返回结果

推荐：

3~8步

不要超过15步

---

## Verification

定义成功标准。

示例：

```yaml
verification:
  - issue_number exists
  - issue_url exists
```

原则：

每个 Skill 必须有验证规则。

---

## Failure Handling

定义失败策略。

示例：

```yaml
permission_denied:
  action: return_error

network_error:
  action: retry

resource_not_found:
  action: return_resource_name
```

原则：

不要只说失败。

要说明：

* 为什么失败
* 如何恢复

---

## Constraints

定义行为边界。

示例：

```yaml
constraints:
  - 不删除数据
  - 不覆盖已有文件
  - 不执行危险命令
```

约束越明确：

执行越稳定。

---

## Examples

至少提供：

* 3个成功案例
* 1个失败案例

示例：

### Example 1

User:

登录页面报错

Expected Action:

创建 Bug Issue

---

### Example 2

User:

增加导出功能

Expected Action:

创建 Feature Issue

````

---

# 4. Recommended Skill Structure

```text
skill/
│
├── SKILL.md
│
├── docs/
│
├── examples/
│
├── references/
│
└── assets/
````

---

## SKILL.md

只存放：

* Metadata
* Use Cases
* Inputs
* Outputs
* Workflow
* Verification
* Examples

---

## docs/

存放详细知识。

例如：

```text
GitHub API说明
Docker命令说明
MySQL规范
```

---

## examples/

存放案例。

例如：

```text
success_case_01.md
success_case_02.md
failure_case_01.md
```

---

# 5. Skill Quality Checklist

发布前检查：

## Discoverability

* [ ] 名称包含动作
* [ ] Description说明用途
* [ ] Tag准确

---

## Decision Quality

* [ ] 定义 when_to_use
* [ ] 定义 when_not_to_use
* [ ] 场景无歧义

---

## Execution Quality

* [ ] 输入完整
* [ ] 输出固定
* [ ] Workflow清晰

---

## Reliability

* [ ] 存在验证机制
* [ ] 存在失败处理
* [ ] 存在约束规则

---

## Examples

* [ ] ≥3个成功案例
* [ ] ≥1个失败案例

---

# 6. Recommended Template

```yaml
name:

description:

tags:

when_to_use:

when_not_to_use:

inputs:

outputs:

workflow:

verification:

failure_handling:

constraints:

examples:
```

---

# 7. Golden Rule

不要问：

"这个 Skill 能做什么？"

而应该问：

"AI 如何准确判断什么时候调用它？"

一个优秀 Skill 的核心：

* 容易发现
* 容易决策
* 容易执行
* 容易验证

如果 AI 能准确回答：

* 为什么调用
* 何时调用
* 如何调用
* 如何验证

那么这个 Skill 就达到了生产级标准。

```