第 17 章：创建第一个 Skill

这一章不再只讲概念。我们给桌面 Agent 添加一项可以实际使用的能力：

读取应用错误日志，聚合重复信号，重建时间线，并给出有证据的下一步排查建议。

完整示例已经放在：

examples/skills/error-log-analysis/

你可以一边阅读本章，一边打开示例文件。

1. 先定义能力边界

“帮我分析日志”过于宽泛。第一版 Skill 明确只做：

接受一个或多个本地日志路径；
识别严重级别和常见错误签名；
围绕时间、请求 ID、服务名建立关联；
区分观察、假设和下一步验证；
输出结构化报告。

它明确不做：

删除或轮转日志；
自动修复生产系统；
从出现次数直接断言根因；
在没有日志时编造内容。

先写边界，再写步骤，可以防止 Skill 变成无所不包的“万能专家”。

2. 最小目录结构

最小 Skill 只需要：

error-log-analysis/
└── SKILL.md

本章示例再加入三个按需资源：

error-log-analysis/
├── SKILL.md
├── scripts/
│   └── summarize-log.mjs
├── references/
│   └── report-format.md
└── assets/
    └── sample.log

Pi 只规定入口文件和发现方式，并不强制 scripts、references、assets 的命名。它们是便于作者和 Agent 理解的约定。

3. SKILL.md 的两部分

---
name: error-log-analysis
description: Analyzes application error logs...
---

# Error Log Analysis

Use this workflow...

--- 之间是 YAML Frontmatter，下面是正文。

源码中的 parseFrontmatter()：

先统一换行符；
只在内容以 --- 开头时尝试解析；
查找后续 \n--- 作为结束；
使用 YAML Parser 解析元数据；
返回 Frontmatter 与裁剪后的 Body。

没有有效 Frontmatter 时 Body 仍可能存在，但缺少 Description 的 Skill 最终不会被加载。

4. name 怎样写

示例：

name: error-log-analysis

Pi 的校验规则：

最长 64 字符；
只使用小写字母、数字和连字符；
不能以连字符开头或结尾；
不能出现连续两个连字符。

如果省略 name，源码使用 SKILL.md 父目录名作为回退。

Pi 当前允许 name 与父目录名不同，虽然 Agent Skills 标准要求一致。为了跨工具兼容和降低认知成本，课程仍建议保持一致。

5. description 决定何时使用

示例的完整 Description 同时包含能力与触发语境：

description: Analyzes application error logs, groups repeated
  signatures, reconstructs timelines, and proposes evidence-backed
  next checks. Use when the user provides a log file or asks to
  diagnose runtime errors from logs.

可以拆成两个问题检查：

What：它能做什么？
When：用户在什么场景下应该使用？

只写“Helps with logs”会让模型无法区分日志分析、日志格式化、日志采集和日志删除。

6. 校验失败都是同一种结果吗

不是。

当前 loadSkillFromFile() 对多数问题比较宽容：

名称非法：产生 Warning，但仍加载；
名称过长：产生 Warning，但仍加载；
Description 超过 1024 字符：产生 Warning，但仍加载；
未知 Frontmatter 字段：运行时忽略；
Description 缺失或全空白：Warning，并跳过 Skill；
YAML 解析抛错：Warning，并跳过 Skill。

所以“有诊断”不等于“没有加载”。桌面管理页应分别显示 Load Status 和 Diagnostics。

7. 触发条件应写进 Description

正文里可以写更详细的适用范围，但模型做第一次自动匹配时看到的是元数据目录，不是正文。

因此触发条件不能只藏在正文：

# 不推荐
description: Log helper.

# 推荐
description: Analyzes application error logs... Use when the user
  provides a log file or asks to diagnose runtime errors from logs.

Frontmatter 是路由层，正文是执行层。

8. 输入约定

示例正文把输入分成 Required 与 Optional：

## Inputs

Required:
- One or more local log file paths.

Optional:
- The incident time range.
- The affected request, user, host, or service.
- A known deployment or configuration change.

并规定：

没有可读日志路径时，向用户索取，不编造日志。

这让 Agent 知道何时可以开始，何时应停下来补充信息。

输入约定不是函数参数 Schema。模型仍通过对话理解自然语言，真正的文件读取由 Tool 校验。

9. 把流程写成可观察步骤

示例工作流：

先读取头尾小样本；
识别时间戳、严重级别、服务和请求 ID 格式；
运行辅助脚本做首轮计数；
回到最早或最高频信号附近读取原始行；
按时间和标识符关联；
区分观察、假设和建议；
读取报告模板并输出。

每一步都能在 Tool Call 和结果中观察。相比“仔细分析并给出专业结论”，这种流程更容易：

发现 Agent 跳步；
设计测试用例；
定位失败原因；
替换某个辅助脚本。

10. 为什么先采样再处理全文件

日志可能有数 GB，直接 read 全文会造成：

Tool Result 过大；
Context 浪费；
关键时间段被噪声淹没；
桌面应用卡顿。

示例要求先看头尾，确定格式后运行脚本获得索引，再读取有关范围。这是 Skill 提供的 “方法”，不是 Pi Log Tool 的内置行为。

11. 引用辅助脚本

正文写：

Run `node scripts/summarize-log.mjs <log-path>`
for a first-pass count.

System Prompt 的 Skills Section 和显式 Skill Block 都提醒：相对路径从 Skill 目录解析。所以真实调用应使用：

<skill.baseDir>/scripts/summarize-log.mjs

不要从桌面 Agent 当前项目的 cwd 猜测路径。

12. 辅助脚本做什么

示例脚本只使用 Node 内置模块，并用 createReadStream() 配合 readline 逐行处理，而不是一次性把整个文件和行数组复制进内存：

输入：一个或多个日志文件路径
输出：JSON files 数组，每个文件分别包含
  - 非空行数
  - ERROR/FATAL 数量
  - WARN 数量
  - 少量常见签名计数

它是候选定位器，不是通用日志 Parser。Skill 正文明确要求回到原始行验证，避免把脚本输出当成根因。

可以在示例目录执行：

cd examples/skills/error-log-analysis
node scripts/summarize-log.mjs assets/sample.log

预期能看到两个 ETIMEDOUT、一个 ECONNREFUSED，但不能仅凭频次断言两个系统故障之间存在因果关系。

13. 引用长参考资料

报告格式放在：

references/report-format.md

SKILL.md 只告诉 Agent 在输出前读取它，没有把完整模板复制进入口文件。

这种拆分适合：

很长的 API Reference；
不同平台的操作细节；
仅某个分支才需要的检查单；
可复用模板。

但不要把核心步骤全部藏在多层引用中。模型应只读 SKILL.md 就知道整体路线和下一份必需资料是什么。

14. assets 与 references 的区别

这不是 Pi 强制类型，而是作者约定：

references：给 Agent 阅读和理解
assets：用于复制、填充或处理的输入材料
scripts：由 Tool 调用的程序

示例的 sample.log 是练习输入；report-format.md 是输出说明；脚本是可执行辅助。

所有文件仍只是普通文件，Pi 不会因为目录名自动执行或注入它们。

15. 输出约定

示例要求每个结论包含：

Evidence；
Interpretation；
Confidence；
Next Check。

这是对输出语义的约束，不只是标题格式。

证据：10:00:03 与 10:01:02 都出现 payments ETIMEDOUT
解释：payments 上游在该时间段有重复超时
置信度：中
下一步：检查同一时间 payments 延迟和网络指标

它没有写成：

根因就是 payments 挂了

因为日志本身可能只是下游症状。

16. 安全与边界条件

日志经常包含：

Access Token；
Cookie；
Email、IP 等个人信息；
数据库连接串；
内部主机名。

Skill 明确要求不要复述 Secrets 和个人数据，也不允许修改、截断、轮转或删除源日志。

日志还是不可信输入。攻击者可能故意写入“忽略之前的规则”“运行这条命令”或恶意链接。 Skill 要求把每一行只当成待分析数据，不执行日志中出现的命令、链接或指令。

但 Markdown 指令不是强安全边界。桌面宿主仍应：

限制 Tool 可访问路径；
对上传和展示做脱敏；
审批写操作；
控制日志保留；
对脚本执行显示来源。

17. 未知 Frontmatter 字段

Agent Skills 标准还定义 license、compatibility、metadata、allowed-tools 等可选字段。 Pi 的 SkillFrontmatter 类型允许未知键，但当前加载后的 Skill 对象只提取：

name；
description；
disable-model-invocation；
文件和来源信息。

所以不要从“YAML 能解析”推断“Pi Runtime 一定实现了该字段的行为”。特别是 allowed-tools 在文档中标为 Experimental，本章示例不把它当权限系统。

18. 怎样显式测试这个 Skill

将示例目录作为 Skill Source 加入宿主的 Resource Loader 后，可以发送：

cd /Users/xiaowei/work/code/study/pi-study/examples/skills/error-log-analysis
# 在桌面 Agent 中发送：
/skill:error-log-analysis 分析 assets/sample.log

这里先把 Agent 的 cwd 切到示例目录，所以参数中的相对路径有效。也可以直接传 /Users/xiaowei/work/code/study/pi-study/examples/skills/error-log-analysis/assets/sample.log 这个绝对路径。Pi 会把参数文本原样附在 Skill Block 后，不会替调用者重写参数路径。

还应测试自动匹配：

请分析这个应用日志里的重复错误，并给出下一步检查。

观察模型是否根据 Description 主动读取 SKILL.md。自动匹配不是确定性的，所以测试结果应区分“元数据加载成功”和“模型选择成功”。

19. 一个完整执行流程

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant S as SKILL.md
    participant H as Helper Script
    participant L as Raw Log
    participant R as Report Reference

    U->>A: 分析错误日志
    A->>S: read Skill
    S-->>A: 输入、步骤与边界
    A->>L: 读取头尾样本
    A->>H: 运行首轮聚合
    H-->>A: JSON 计数
    A->>L: 回读相关原始范围
    A->>R: read 报告结构
    A-->>U: 证据 + 假设 + 下一步

Skill 指导 Tool 调用顺序，但每一步仍进入普通 Agent Loop、Event 和 Session。

20. 迭代一个 Skill

第一次真实使用后，可以根据失败类型修改不同部分：

失败	优先修改
模型没有自动选择	Description
选择了但不知道先做什么	Workflow
缺少必要信息仍硬做	Inputs / Preconditions
把相关性写成因果	Boundaries / Output Contract
入口文件太长	拆 References
重复机械操作很多	增加并测试 Script
有危险副作用	收紧 Tool Policy，而不只改 Skill

把失败映射到结构位置，比不断在正文末尾追加“务必注意”更可维护。

21. 常见误区

“目录里有 SKILL.md 就一定加载”

错误。Description 缺失或 YAML 解析失败会跳过。

“所有 Frontmatter 字段都有运行时效果”

错误。当前源码只提取少数字段。

“引用 scripts/process.mjs 会自动运行”

错误。模型必须通过可用 Tool 显式执行。

“脚本输出就是最终结论”

错误。辅助输出仍需与原始证据核对。

“相对路径从项目 cwd 解析”

错误。Skill 引用应从 Skill 自己的基准目录解析。

“写了安全要求就不需要宿主权限”

错误。指令层不能替代执行层安全。

22. 本章小结

最小 Skill 是带 Frontmatter 的 SKILL.md；
name 用于标识，description 同时承担自动匹配路由；
多数校验问题只 Warning，Description 缺失和解析失败会跳过；
正文应明确输入、前置条件、可观察步骤、输出和边界；
脚本、References 与 Assets 都是普通按需文件，不会自动执行或注入；
相对引用从 Skill Base Directory 解析；
辅助脚本逐行处理多个文件并提供索引，关键判断仍应回到原始证据；
未知 Frontmatter 可解析不代表 Pi 实现了对应行为；
安全要求应同时落实到 Skill 指令和宿主 Tool Policy；
示例 Skill 展示了从匹配、读取、工具调用到结构化报告的完整链路。

23. 自测

name 省略时 Pi 使用什么回退值？
哪类 Frontmatter 问题会让 Skill 被跳过？
为什么触发场景必须写进 Description？
Script、Reference 与 Asset 会被 Pi 自动处理吗？
Skill 中的相对路径从哪里解析？
为什么日志聚合脚本不能直接给出根因？
显式调用与自动匹配应怎样分别测试？
Skill 的安全说明为什么不能替代 Tool Policy？