Skill包含哪些文件？文件结构与每个文件的职责全解

Skill本质上是一个标准化目录，其中至少包含一个 SKILL.md 文件作为能力入口，同时可根据需求添加 scripts/、references/、assets/ 等子目录来承载脚本、参考文档和静态资源。理解每个文件的作用，是正确编写、安装和调试技能的基础。本文逐层拆解一个典型Skill目录内的全部文件，说明其用途、格式和注意事项。

本文大纲

• 根目录下的唯一必需文件：SKILL.md
• 可执行脚本目录：scripts/
• 参考资料目录：references/
• 静态资源目录：assets/
• 生命周期配置文件：lifecycle.yaml（可选）
• 人类可读说明：README.md（可选）
• 平台对文件大小、数量和类型的限制
• 目录命名与层级规范

---

一、根目录下的唯一必需文件：SKILL.md

SKILL.md 是Skill的入口文件，必须位于技能目录的根目录下，且文件名严格区分大小写。

文件结构：

• YAML Frontmatter（元数据块） ：用 --- 包裹在文件最顶部，定义技能的名称、描述、许可等关键属性。其中 name 和 description 为必填项。
  • name：小写字母、数字和连字符组成，1-64字符，须与父目录名一致。
  • description：概述技能的作用和触发场景，最长1024字符。
  • 可选字段：license、compatibility、metadata、allowed-tools（实验性）等。
• Markdown正文（指令体） ：Frontmatter之后的所有内容均为自然语言指令，描述执行步骤、判断逻辑、输入输出示例等。Agent加载后会依据此部分来完成任务。

示例片段：

---
name: pdf-summarizer
description: Extract key points from PDF documents and generate a concise summary. Use when user uploads a PDF and asks for a summary.
---

# PDF Summarizer
1. Read the uploaded PDF file.
2. Extract headings and first sentences of each paragraph.
3. Output a bullet-point summary.

二、可执行脚本目录：scripts/

该目录存放辅助任务执行的代码文件，用于处理计算密集、需精确控制的操作（如数据解析、格式转换、API调用等）。

• 支持语言：Python（.py）、Bash（.sh）、Node.js（.js/.ts）等。
• 调用方式：Agent会在执行SKILL.md指令时，根据需要调用这些脚本，并将输出结果合并到最终回复中。
• 设计原则：每个脚本应承担单一职责，并包含必要的错误处理，以便Agent能够捕获异常并反馈给用户。

示例：

my-skill/
├── SKILL.md
└── scripts/
    ├── extract_text.py
    └── count_tokens.py

三、参考资料目录：references/

该目录存放非执行性的长篇文档、规范说明、API手册等，供Agent在需要时按需引用。

• 文件格式：.md、.txt、.json、.yaml 等纯文本格式。
• 加载机制：Agent不会在每次对话中全部加载，只有当指令中明确提及或用户询问时才会读取对应文件，从而节约上下文Token。
• 典型内容：详细的字段映射表、合规性说明、配置参数详解等。

四、静态资源目录：assets/

该目录存放模板、图片、字体等二进制或静态文本文件，用于在输出中引用。

• 文件格式：.png、.jpg、.svg、.pdf、.docx 模板等。
• 使用场景：生成报告时套用模板，或在对话中展示示例图表。
• 注意：由于文件可能较大，请控制单个文件大小不超过平台限制（参见第六节）。

五、生命周期配置文件：lifecycle.yaml（可选）

位于根目录下的 lifecycle.yaml 文件用于定义Skill在安装、更新、卸载时的自动化钩子。

• 典型字段：
  • on_install：安装后执行的命令（如创建必要目录、下载依赖）。
  • on_update：更新时执行的命令。
  • on_uninstall：卸载前执行的清理命令。
• 用途：当Skill需要系统级依赖或环境配置时，可使用此文件实现自动化运维。

六、人类可读说明：README.md（可选）

README.md 是面向开发者或用户的说明文档，与 SKILL.md 区分开来。它通常包含技能的设计思路、版本历史、依赖项、配置示例等，帮助人类快速了解技能背景，而 SKILL.md 则专门服务于Agent。

七、平台对文件大小、数量和类型的限制

在SkillHub等平台上发布技能时，需注意以下技术限制（以SkillHub官方为准）：

项目	限制值（可调整）
单文件最大大小	1 MB
整个技能包总大小	10 MB
文件总数	100 个
允许的文件扩展名	.md, .txt, .json, .yaml, .yml, .js, .cjs, .mjs, .ts, .py, .sh, .png, .jpg, .svg

上传时，平台会校验文件类型，并自动归一化大小写（如 skill.md 会被视为 SKILL.md）。

八、目录命名与层级规范

• 目录名称：必须全小写，仅含字母、数字和连字符（-），不能以连字符开头或结束，也不能包含连续连字符（如 "my--skill" 无效）。
• 层级深度：Skill目录必须为单层结构，即所有文件及 scripts/、references/、assets/ 等子目录都直接位于根目录下，不支持嵌套子技能。
• 一致性要求：根目录名必须与 SKILL.md 中的 name 字段值完全一致。

合法示例：

pdf-tool/                # 目录名 = name
├── SKILL.md             # 必需
├── scripts/
│   └── parse.py
├── references/
│   └── api.md
└── assets/
    └── logo.png

非法示例：

PDF-Tool/                # 包含大写字母
├── SKILL.md
└── sub-skill/           # 不允许嵌套子目录
    └── SKILL.md

---

总结

一个完整的Skill文件结构可归纳为：一个核心入口文件（SKILL.md） + 三个标准可选目录（scripts/、references/、assets/） + 若干辅助配置文件（lifecycle.yaml、README.md等）。SKILL.md承载元数据和执行指令，是Agent行为的唯一依据；scripts/提供精确计算能力，references/提供扩展背景，assets/提供静态素材。发布前需核对目录命名、文件大小和类型是否符合平台规范，并保持单层扁平结构。

如果你正在使用实在Agent 7.3.6，通过技能中心的上传文件夹或ZIP包导入技能时，只需保证目录结构符合上述规范——根目录包含有效的SKILL.md，且所有可选子目录按要求组织——上传后Agent会自动解析并加载，无需手动调整任何路径或配置，便可立即在对话中调用该技能。