SKILL 使用指南¶

读者对象：Agent 开发者
预计阅读时间：1.5 小时
版本：v0.1 | 2026-08-13

1. SKILL 概念¶

1.1 什么是 SKILL？¶

SKILL 是 PE Agent 平台上的可复用 AI 能力包，遵循「Thin Harness, Fat Skills」理念：

Harness（承载层）：Agent 工作流负责调度与上下文
Skill（技能层）：SKILL 文件承载领域知识、操作规范与脚本

一个 SKILL 相当于给 LLM 的专业操作手册，可在多个 Agent 中复用。

1.2 SKILL 与 Agent / Tool 的关系¶

组件	职责
Agent	编排任务流程，决定何时调用 Skill
SKILL	提供领域知识与执行规范
Tool / 插件	提供可执行代码能力（计算、API 调用等）

Agent 通过 Prompt 中的 <skills> / <my_skills> 咒语加载 SKILL，LLM 按需读取 SKILL.md 及参考文件。

1.3 三层加载架构¶

层级	内容	加载时机
第 1 层	所有 Skill 的 name + description	系统 Prompt 预加载
第 2 层	完整 SKILL.md	LLM 需要时读取
第 3 层	references/、scripts/ 等资源	按需读取

这样设计可节省 Token，同时保持专业能力可扩展。

2. SKILL 目录结构¶

标准 SKILL 包结构：

my-skill/
├── SKILL.md          # 核心指令（必填）
├── README.md         # 人类可读说明（可选）
├── references/       # 参考文档
│   └── spec.md
├── scripts/          # 可执行脚本
│   └── calc.py
└── examples/         # 示例
    └── case1.md

2.1 SKILL.md 规范¶

文件开头使用 YAML frontmatter：

---
name: buck-calculator
description: Buck 电路 CCM 模式参数计算规范与检查清单
---

# Buck Calculator Skill

## 何时使用
当用户需要计算 Buck 变换器参数时激活本 Skill。

## 计算步骤
1. 确认工作模式（CCM/DCM/BCM）
2. ...

要点：

name：唯一标识，供 <skills names="..."> 引用
description：简短说明，用于第 1 层元数据展示
正文：LLM 的执行指令，建议 < 500 行

3. 创建个人 SKILL¶

3.1 方式一：使用 `<save_to_skill>` 咒语¶

在 Agent 节点 Prompt 或 LLM 输出中：

<save_to_skill dir="buck-calculator/SKILL.md">
---
name: buck-calculator
description: Buck 电路参数计算
---

# Buck Calculator
（完整 SKILL 内容）
</save_to_skill>

文件保存至平台 skills/skills/buck-calculator/SKILL.md。

3.2 方式二：导入现有 SKILL 包¶

若已有符合规范的 SKILL 目录，可通过后端或管理流程放入 skills/skills/ 目录（具体导入方式联系管理员）。

3.3 命名建议¶

使用小写字母、连字符：buck-calculator、llc-design-review
description 一句话说明适用场景
领域 + 动作：pfc-param-calc、inverter-spec-check

4. 在 Agent 中使用 SKILL¶

4.1 引用公开 SKILL¶

在节点 系统提示词 中加入：

<skills names="buck-calculator,guizang-ppt-skill" />

或使用模糊匹配：

<skills names_like="buck*" />

4.2 引用个人 SKILL¶

<my_skills names="my-buck-calculator" />

个人 SKILL 仅创建者可用。

4.3 读取 SKILL 文件内容¶

<skills_file path="buck-calculator/references/formulas.md" />

4.4 修改 SKILL 内容¶

高级场景可使用 <replace_skills_file_content> 更新已有 SKILL 文件（需谨慎，避免覆盖团队共享 Skill）。

5. SKILL 管理操作¶

5.1 复制文件到个人目录¶

<copy_to_mydir dir="项目资料/" />

需先上传附件，将文件复制到 documents/{手机号}/项目资料/。

5.2 删除个人文件¶

<del_from_myself_dir dir="path/to/file.md" />

5.3 删除个人目录¶

<del_my_dir dir="临时目录/" />

6. 内置 SKILL 示例¶

平台 skills/skills/ 下已有多种示例，可供参考：

类型	示例	用途
PPT 生成	guizang-ppt-skill	HTML/PPT 演示文稿
文档编辑	NQ-PPT-HTML-Editor	PPT HTML 编辑
领域知识	hr_management_distilled	HR 领域 playbook
API 集成	claude-api	API 调用规范

阅读其 SKILL.md 和 README.md 可学习编写模式。

7. 编写最佳实践¶

7.1 结构清晰¶

## 何时使用
## 输入要求
## 执行步骤
## 输出格式
## 注意事项
## 示例

7.2 可执行性¶

步骤具体、可验证
公式、阈值写清楚
提供正例/反例

7.3 与 Agent 分工¶

SKILL 负责	Agent 负责
领域规范、检查清单	流程编排、用户交互
计算公式、模板	多节点协作、工具调用
参考文档索引	任务级变量、结果汇总

7.4 版本与维护¶

重大变更时在 SKILL.md 顶部注明版本
团队共享 Skill 变更需评审
个人 Skill 可快速迭代

8. 案例：创建 Buck 计算 SKILL¶

8.1 目标¶

将 Buck CCM 计算规范封装为 Skill，供多个 Agent 引用。

8.2 SKILL.md 骨架¶

---
name: buck-ccm-calculator
description: Buck 变换器 CCM 模式参数计算与校验
---

# Buck CCM Calculator

## 何时使用
用户提供了 Vin, Vout, Iout, Fsw 等参数，需要计算占空比、纹波、器件应力。

## 输入检查
- Vin, Vout, Iout, Fsw 必填
- 确认 Vout < Vin（Buck 拓扑）

## 计算公式
- 占空比 D = Vout / Vin
- ...

## 输出格式
Markdown 表格，列：参数名、符号、数值、单位

## 注意事项
- 结果需标注工作模式假设
- 关键结论提醒人工复核

8.3 在 Agent 中引用¶

节点 Prompt 开头：

<my_skills names="buck-ccm-calculator" />

请根据用户输入，按 Skill 规范完成 Buck 参数计算。

9. 延伸阅读¶

咒语使用文档 — save_to_skill、skills、my_skills
智能体（Agent）
共享方案