目录结构

一个 Skill 在文件系统中以独立目录的形式存在，目录内通过约定俗成的文件与子目录划分职责。agentskills.io 开放标准约定的标准三件套是：

my-skill/
├── SKILL.md       ← 核心（必需）— 元数据 + 指令
├── scripts/       ← 可选 — 可执行脚本
├── references/    ← 可选 — 详细参考文档
└── assets/        ← 可选 — 静态资源（模板、图片、数据文件）

各组成部分的职责如下：

目录	职责	加载时机
SKILL.md	Skill 的核心入口，必需；包含 YAML 元数据 + Markdown 指令	两阶段：元数据始终加载，正文命中时加载
scripts/	可执行代码（Python / Bash / JS 等），扩展 AI 的执行能力，强调确定性操作	被显式调用时执行，不进上下文
references/	详细文档、领域知识、API schema、cheatsheet 等深度参考资料	按需读取，用到才进上下文
assets/	静态资源——文档模板、配置模板、图表、数据文件	被引用 / 复制时使用

TIP

建议：起步阶段保持最小化——一个目录 + 一个 SKILL.md 已足够覆盖绝大多数场景。能力扩展时，再按需引入 scripts/ / references/ / assets/。允许引入领域专用的额外目录（如 templates/），但优先复用上述三个标准目录，便于跨平台与工具链识别。

命名约定

• 目录名 = SKILL.md 中 name 字段值——这是 spec 的硬约束
• 全部小写，单词用连字符连接（kebab-case），如 pdf-form-filler、code-reviewer
• 不能以连字符开头/结尾，不能含连续连字符
• 不能包含保留词 claude、anthropic
• 长度 1–64 字符
• Anthropic 内部偏好 verb-ing + noun 形式（如 analyzing-marketing-campaign），让 description 更自然

几条容易踩的坑

WARNING

同目录禁放 README.md。Anthropic 官方明确建议：所有面向 AI 的文档都应在 SKILL.md 或 references/ 里。如果你需要给人类读者写说明（例如分发到 GitHub），把 README.md 放在仓库根，而不是 skill 目录内。

WARNING

路径一律用正斜杠 /。即使在 Windows 上写 skill，也要用 scripts/foo.py 而非 scripts\foo.py——agent 在 Linux 容器里执行时反斜杠会直接报错。

TIP

引用层级保持一层。SKILL.md 直接引用 scripts/x.py 或 references/y.md，不要嵌套到 references/db/v1/schema.md 这样的深层路径——agent 容易找不到。

下一步

掌握目录结构后，就可以打开 SKILL.md 学习这个核心文件该怎么写。