skill-authoring

创建扩展代理功能的有效 SKILL.md 文件的指南。在创建新技能、更新现有技能或教授客服人员专业工作流程时使用。

# Skill Authoring Guide

agentskills.io 표준에 맞는 효과적인 스킬 작성법.

## 핵심 원칙

### 1. 간결함이 왕
컨텍스트 윈도우는 공공재다. 모든 스킬이 이 공간을 공유한다.

**기본 가정: 에이전트는 이미 매우 똑똑하다.**
에이전트가 모르는 것만 추가할 것. 모든 문장마다 자문:
- "이 설명이 정말 필요한가?"
- "이 단락이 토큰 비용을 정당화하는가?"

장황한 설명보다 간결한 예제를 선호.

### 2. 자유도 매칭

| 자유도 | 언제 | 형태 |
|--------|------|------|
| **높음** | 여러 접근법이 유효, 맥락에 따라 판단 | 텍스트 지침 |
| **중간** | 선호 패턴 존재, 일부 변형 허용 | 의사코드/파라미터 있는 스크립트 |
| **낮음** | 취약한 작업, 일관성 필수 | 구체적 스크립트, 최소 파라미터 |

좁은 다리(절벽 옆) = 구체적 가드레일 (낮은 자유도)
넓은 평원 = 다양한 경로 허용 (높은 자유도)

## SKILL.md 구조

```yaml
---
name: my-skill-name        # 필수, 소문자+하이픈, 1-64자
description: >             # 필수, 1-1024자
  무엇을 하는지 + 언제 사용하는지 + 관련 키워드
license: Apache-2.0        # 선택
metadata:                  # 선택
  author: misskim
  version: "1.0"
---

# 스킬 제목

[에이전트가 따를 지침 - 마크다운 자유형식]
```

### 필수 필드
- **name:** 디렉토리명과 일치, 소문자+하이픈만
- **description:** 스킬 활성화 트리거 역할 → 키워드 풍부하게

### 디렉토리 구조
```
skill-name/
├── SKILL.md          # 필수
├── scripts/          # 실행 코드 (Python/Bash/JS)
├── references/       # 상세 문서 (필요 시 로드)
└── assets/           # 정적 리소스 (템플릿, 이미지, 데이터)
```

## 우리 환경 특화 고려사항

1. **Clawdbot 에이전트:** skills/ 또는 ~/.clawdbot/skills/에 배치
2. **MiniPC 연동:** nodes.run 명령으로 외부 작업 위임 가능
3. **서브에이전트:** 스킬이 서브에이전트를 스폰하도록 설계 가능
4. **보안:** scripts/ 코드는 신뢰할 수 있는 것만 포함
5. **SKILL.md 500줄 이하 유지** — 상세 내용은 references/로 분리

## 나쁜 스킬 vs 좋은 스킬

**나쁜:** "PDF를 처리합니다" (description이 너무 짧음)
**좋은:** "PDF 파일에서 텍스트/표를 추출하고, 폼을 채우고, 여러 PDF를 병합합니다. PDF 문서 작업이나 문서 추출을 언급할 때 사용."

**나쁜:** 에이전트가 이미 아는 Python 문법 설명
**좋은:** 에이전트가 모르는 도메인 특화 지식/워크플로우 제공

---

## 中文说明

# 技能编写指南

符合 agentskills.io 标准的有效技能编写方法。

## 核心原则

### 1. 简洁为王
上下文窗口是公共资源。所有技能都共享这一空间。

**基本假设：代理已经非常聪明。**
只添加代理不知道的内容。对每个句子都自问：
- "这段说明真的有必要吗？"
- "这一段是否值得它消耗的 token 成本？"

相比冗长的说明，更倾向于简洁的示例。

### 2. 匹配自由度

| 自由度 | 何时使用 | 形式 |
|--------|------|------|
| **高** | 多种方法均有效，依语境判断 | 文本指引 |
| **中** | 存在偏好模式，允许部分变化 | 带参数的伪代码/脚本 |
| **低** | 脆弱的任务，必须保持一致性 | 具体脚本，参数最少 |

狭窄的桥（紧邻悬崖）= 具体的护栏（低自由度）
宽阔的平原 = 允许多样的路径（高自由度）

## SKILL.md 结构

```yaml
---
name: my-skill-name        # 필수, 소문자+하이픈, 1-64자
description: >             # 필수, 1-1024자
  무엇을 하는지 + 언제 사용하는지 + 관련 키워드
license: Apache-2.0        # 선택
metadata:                  # 선택
  author: misskim
  version: "1.0"
---

# 스킬 제목

[에이전트가 따를 지침 - 마크다운 자유형식]
```

### 必填字段
- **name:** 与目录名一致，仅小写字母+连字符
- **description:** 充当技能激活的触发器 → 关键词要丰富

### 目录结构
```
skill-name/
├── SKILL.md          # 필수
├── scripts/          # 실행 코드 (Python/Bash/JS)
├── references/       # 상세 문서 (필요 시 로드)
└── assets/           # 정적 리소스 (템플릿, 이미지, 데이터)
```

## 针对我们环境的特别注意事项

1. **Clawdbot 代理：** 放置在 skills/ 或 ~/.clawdbot/skills/ 中
2. **MiniPC 联动：** 可通过 nodes.run 命令将外部任务委派出去
3. **子代理：** 技能可设计为生成子代理
4. **安全：** scripts/ 中的代码只应包含可信任的内容
5. **SKILL.md 保持在 500 行以内** — 详细内容拆分到 references/ 中

## 糟糕的技能 vs 优秀的技能

**糟糕：** "处理 PDF"（description 太短）
**优秀：** "从 PDF 文件中提取文本/表格、填写表单、合并多个 PDF。在涉及 PDF 文档操作或文档提取时使用。"

**糟糕：** 解释代理已经知道的 Python 语法
**优秀：** 提供代理不知道的领域特定知识/工作流