bp-skill-authoring

Files (2)

• SKILL.md
• full-best-practices.md · reference/

SKILL.md (first lines)

# 编写 Agent Skills

## 语言规范

**Skills 使用中文编写**，包括：
- `description`：中文描述
- 章节标题和说明：中文
- 代码示例和标识符：保持英文

## YAML Frontmatter

```yaml
---
name: processing-pdfs                    # 小写，连字符，最多 64 字符
description: 从 PDF 文件中提取文本...      # 中文，第三人称，做什么 + 何时用，最多 1024 字符
---
```

**name 格式：**
- 推荐动名词：`processing-pdfs`, `analyzing-data`, `testing-code`
- 名词短语也可：`pdf-processing`, `data-analysis`
- ❌ 避免：`helper`, `utils`, `tools`, `anthropic-*`, `claude-*`

**description 规则：**
- ✅ 使用**中文**，第三人称："从 PDF 文件中提取文本"
- ❌ 避免："我可以帮你..."、"你可以用这个来..."
- 包含：做什么 + 何时使用 + 关键词

## 核心原则

### 精简至上

只添加 AI 尚不知道的信息：

```markdown
✅ 好（~50 tokens）：
## 锁
使用 TDMutex，不要用 std::mutex：
tdstore::common::TDMutex mutex_;

❌ 差（~150 tokens）：
## 锁
线程安全在多线程应用中很重要。
TDStore 使用 bthread 协程，所以需要特殊的锁...
```

### 约束条件

- SKILL.md 正文：**< 500 行**
- 引用深度：从 SKILL.md 起**只能一层**
- 文件路径：**只用正斜杠**（`reference/guide.md`）

## 项目 Skills 目录结构

```
skills/
├── <skill-name>/                    # 通用技能
│   └── SKILL.md
└── <module>/                        # 模块专项技能
    └── <skill-name>/
        └── SKILL.md
```

**示例：**
```
skills/
├── writing-skills/                  # 通用：编写 Skills 指南
│   ├── SKILL.md
│   └── reference/
└── backend/                         # 模块：后端
    ├── coding-standards/            # 编码规范
    │   └── SKILL.md
    └── storage-modifications/       # 存储改造规范
        └── SKILL.md
```

**命名规则：**
- 模块名：`backend`, `storage`, `scheduler` 等
- 技能名：`coding-standards`, `storage-modifications`, `testing` 等
- 使用小写 + 连字符

## 渐进式披露

单个 Skill 内部结构：

```
skill-name/
├── SKILL.md              # 概览（触发时加载）
├── reference/
│   ├── topic-a.md        # 按需加载
│   └── topic-b.md
└── scripts/
    └── validate.py       # 执行，不加载到上下文
```

在 SKILL.md 中链接到详情：

```markdown
## 快速开始
[基本用法]

## 进阶
**主题 A**：参见 [reference/topic-a.md](reference/topic-a.md)
**主题 B**：参见 [reference/topic-b.md](reference/topic-b.md)
```

## 常用模式

### 模板模式

```markdown
## 输出格式

始终使用以下结构：
# [标题]
## 摘要
## 发现
## 建议
```

From davidYichengWei/agentic-engineering-framework, MIT.

More from davidYichengWei/agentic-engineering-framework