create-skills

Instructions（分步说明）

Step 1：确认目录结构

每个 skill 至少包含 SKILL.md，可选 scripts/、references/、assets/。完整格式规范见 references/specification.md（来源：agentskills.io/specification）。

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional
├── references/       # Optional
└── assets/           # Optional

目录名必须与 frontmatter 中的 name 一致（小写、连字符、1–64 字符）。

规则设计时的命名约定（创建/修改 skill 时适用）：除必要外，所有文件名与目录名使用小写。

• 默认：新建或重命名的文件、目录均使用小写。
• 「必要」：仅当规范/框架明确要求某命名时不改为小写（如 SKILL.md、README.md、Makefile）。强制规范 > 本约定。
• 不确定时：先查该规范文档；未写明则使用小写。

Step 2：编写 frontmatter

必填两项：

• name：与目录名一致，仅 a-z、0-9、-，不以 - 开头或结尾，无 --
• description：做什么 + 何时用，含关键词，1–1024 字符，第三人称

Step 3：编写正文

YAML 之后为 Markdown 正文。推荐包含：

• Instructions（分步说明）
• Examples（输入/输出示例，若适用）
• Edge cases（常见边界情况，若适用）

Step 4：自检与验证

• 目录名 = name
• description 含「做什么」「何时用」和关键词
• 引用文件仅一层深度，用相对路径
• 若环境支持：skills-ref validate ./skill-name

---

Example（最小可用 skill）

输入：用户要一个「处理 PDF」的 skill。

输出：创建目录 pdf-processing/，其中 SKILL.md 至少为：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Instructions
1. ...

---

常见边界情况

• name 与目录不一致：必须一致，否则部分客户端无法发现
• 文件名与目录名：规则设计时适用上述「除必要外小写」约定；目录名与 name 一致故自然小写
• description 过泛（如 "Helps with PDFs"）：代理难以匹配，应写清「做什么 + 何时用 + 关键词」
• SKILL.md 超 500 行：拆到 references/，正文只保留要点并链接
• 引用多层文件：从 SKILL.md 只引用一层（如 references/SPEC.md），避免 references/a/b.md

---