好，现在我们来系统讲解Skill 的目录结构。前面我们讲的SKILL.md是Skill的"大脑"，而目录结构则是Skill的"身体"——它决定了脚本、参考文档、模板等资源如何组织，以及Agent在执行时如何按需加载它们。
一个 Skill 最少只需要一个文件：
.png)
my-skill/
└── SKILL.md # 唯一必需文件
只要SKILL.md的frontmatter中name和description填写正确，这个 Skill就能被Agent识别和激活。
企业落地时的复杂业务场景推荐使用完整目录结构，通过分层实现职责解耦：
my-skill/
├── SKILL.md # 必需：核心配置 + 执行指引
├── scripts/ # 可选：可执行脚本
│ ├── main.py
│ └── utils.py
├── references/ # 可选：按需加载的参考文档
│ └── policy_excerpt.md
├── assets/ # 可选：模板、样例等静态资源
│ └── report_template.docx
├── examples/ # 可选：少样本输入输出示例
│ └── example1.md
├── tests/ # 可选：测试用例
│ └── test_cases.md
└── CHANGELOG.md # 可选：版本变更记录
scripts/ 目录存放Skill依赖的可执行脚本，支持Python、Bash、Node.js等任意语言。Agent在执行Skill时，通过 allowed-tools中声明的Bash权限来调用这些脚本。
Agent（LLM）擅长推理和生成文本，但不擅长精确的数值计算、文件解析、API调用等确定性任务。scripts/的作用就是把这类"确定性操作"从自然语言指令中剥离出来，交给脚本执行，确保结果100% 可靠：
规范一：脚本必须独立可运行
每个脚本都应该能独立执行，不依赖 Agent 的上下文状态：
# scripts/extract.py
# 通过命令行参数接收输入，通过stdout输出结果
import sys
import json
pdf_path = sys.argv[1]
# ... 处理逻辑 ...
print(json.dumps(result))
规范二：输入输出约定清晰
在SKILL.md的正文中，必须逐一说明每个脚本的功能、参数和输出格式：
## 工具定义
### scripts/extract.py
从PDF中提取结构化数据。
- 输入：`python3 scripts/extract.py <pdf_path> --format json`
- 输出：JSON 格式的键值对，写入 stdout
- 错误：非零退出码 + stderr 输出错误信息
### scripts/validate.sh
校验提取结果的完整性。
- 输入：`bash scripts/validate.sh <json_path>`
- 输出：校验通过返回0，失败返回1并输出缺失字段
规范三：错误处理要完善
脚本失败时，必须通过非零退出码+stderr告知Agent具体错误原因，而不是默默失败或输出到stdout：
# 正确的错误处理
if not os.path.exists(pdf_path):
print(f"Error: file not found: {pdf_path}", file=sys.stderr)
sys.exit(1)
| 脚本类型 | 用途 | 示例 |
|----------|------|------|
| 数据处理 | 解析、转换、计算 | `extract.py`、`analyze.py` |
| 校验检查 | 验证输入/输出合规性 | `validate.sh`、`lint.py` |
| 格式转换 | 文件类型转换 | `html2pptx.py`、`csv2json.py` |
| API 调用 | 与外部服务交互 | `fetch_data.py`、`deploy.sh` |
| 工具函数 | 被其他脚本复用的公共逻辑 | `utils.py`、`helpers.sh` |
认识Agent skill
skill规范详解（1）— 目录结构和name字段
skill规范详解（3）— license字段
skill规范详解（3）— license字段
skill规范详解（4）— metadata字段
skill规范详解（5）— allowed-tools字段
skill规范详解（6）— content正文部分
skill规范详解（7）— scripts目录
skill规范详解（8）— references目录
skill规范详解（9）— assets目录
skill规范详解（10）— examples目录
skill规范详解（11）— tests目录
