| name | agent-build-skill |
| description | 编写办事 SKILL.md:frontmatter name/description、正文步骤、references;创建或改技能结构时用 |
读者:办事助手。本仓目录卡由 @mariozechner/pi-coding-agent 解析;只有 name + description 进 <available_skills>。
模型怎么「看见」技能
- System 里出现
<available_skills>:<name> + <description> + <location>
- 任务匹配 description → 调
tools.read,filePath = location(或相对工作区的 skills/.../SKILL.md)
- 读完正文再按步骤调其它 MCP
因此:description 必须含触发语(用户会怎么说);正文必须是可执行步骤,不要写长散文。
本仓不靠 frontmatter triggers 做目录匹配(那是别家运行时);想要 triggers 式短触发,用 agents/microagents/,不是 SKILL。
最小可运行形
skills/my-skill/ # 工作区自建;或种子 agents/skills/standard/...
└── SKILL.md
可选:references/、scripts/、assets/(长文按需再 read;相对路径相对技能目录解析)。
---
name: my-skill
description: 何时用:用户说「…」时加载;做什么一句话
---
1. …
2. 需要改文件 → 先 read agent-tools 约定,再用 search_replace
| 字段 | 要求 |
|---|
name | 与目录名一致;小写+连字符 |
description | 中文可;写清触发场景,目录卡靠它 |
验收:用一句用户原话,看能否在目录卡对上 name;tools.read 后能否不凭印象完成任务。
放到哪(XRK)
| 目标 | 路径 |
|---|
| 用户定制(推荐) | data/ai-workspace/{id}/skills/<名>/ ← 相对 cwd 即 skills/<名>/ |
| 产品默认种子 | agents/skills/standard/<名>/ 或 .../core/<名>/ |
| 禁止 | .cursor/skills/xrk-*、仓库根随便建 |
安装落盘见 agent-skillhub。
写法要点(AI 能懂)
- 先步骤后解释;表格列工具名用本仓真实名(
tools.read / tools.search_replace)
- 失败写「若…则…」;禁止「酌情处理」无落点
- 一技能一职责;交界写「详见 agent-xxx」
- 勿在 SKILL 里复制整份 MCP 参数表(那是 agent-tools)