Skills 速查

1. 一句话定义

Skill 是一份可被 Agent 发现、按需读取并遵循的专业工作方法。它主要改变“怎样完成任务”， 不直接赋予新的系统权限。

2. 与其他机制对比

3. 最小目录

my-skill/
└── SKILL.md

复杂 Skill：

my-skill/
├── SKILL.md
├── references/
│   └── protocol.md
├── scripts/
│   └── validate.mjs
└── assets/
    └── template.md

SKILL.md 是入口。相对路径以该文件所在目录解析。

4. Frontmatter

至少要让名称和描述清楚表达：

• 它解决什么任务；
• 什么时候应该使用；
• 什么时候不应该使用；
• 需要哪些工具/输入。

Description 是发现阶段的重要摘要。过宽会误触发，过窄会找不到。

5. 渐进式加载

发现 Skill Metadata
→ 摘要进入可用 Skill 列表
→ 模型判断相关
→ 读取完整 SKILL.md
→ 按需读取 reference/script/asset

“列表中存在”不等于“本次任务已经使用”。

若 Frontmatter 设置 disable-model-invocation: true，Formatter 会把该 Skill 从模型可见列表 排除；它只能通过显式 /skill:name 使用，并且宿主要启用 Skill Commands。

6. 显式调用与自动匹配

• 显式：用户/宿主明确指定 Skill；
• 自动：模型根据任务与 Description 选择。

两者最后都要进入完整指令内容。显式调用减少发现不确定性，但仍不能绕过 Tool Policy。

7. 高质量 Skill 模板

---
name: diagnose
description: 当用户要求定位软件故障、分析错误日志或提出修复方案时使用。
---

# Goal

给出有证据、可复现、最小修改的诊断。

# Inputs

- 工作区路径
- 错误现象

# Workflow

1. 读取错误与相关配置
2. 建立候选原因
3. 用证据排除
4. 提出最小修复
5. 验证

# Safety

- 未确认前不执行破坏性操作
- 不读取工作区外敏感文件

# Output

- 原因
- 证据
- 修复
- 验证

8. 编写原则

• 一步一动作；
• 先证据、后结论；
• 明确输入、输出和停止条件；
• 把高风险动作交给 Tool/Host Policy；
• 引用文件只在需要时读取；
• 脚本优先复用，不让模型重写大段机械代码；
• 给失败和缺依赖提供降级路径。

9. 发现与冲突

Skill 可来自用户级、项目级、Package 或额外路径。多个来源同名时要看 Resource Loader 的 优先级与 Diagnostics，不能依赖“碰巧先扫描到”。

项目级 Skill 是否加载还受 Project Trust 影响。

10. 安全边界

Skill 内容是 Prompt 指令，不是 Sandbox：

• 不能授予文件权限；
• 不能保证模型必然遵守；
• 不能替代 Approval；
• 不能把不可信网页内容提升为 System 指令；
• 引用的 Script/Dependency 仍需审查。

11. 测试清单

• Frontmatter 可解析
• Description 正确触发/不误触发
• 所有相对引用存在
• 必需 Tool 已提供
• 读取完整 SKILL.md
• 正常路径符合 Workflow
• 缺文件/禁 Tool 有可见失败
• 高风险动作不能绕过宿主 Policy
• Golden Tasks 在支持模型矩阵通过
• Package/升级后无冲突

12. 分发

可通过项目目录、用户目录或 Pi Package 分发。Package 能同时携带 Skill 与 Extension，安装前 必须分别审查文本指令、脚本、依赖和本地代码权限。

13. 常见问题

源码入口：resource-loader.ts、Skills 文档、System Prompt Formatter。