SKILL的组织技巧以及SKILLS于TOOLS的关系

哪些内容应该放在SKILL.md主文件，哪些放在引用文件？

SKILL.md 主文件应放内容 （官方建议 SKILL.md 控制在 500 行以内。为什么是 500 行？）

• YAML 元数据
  • name
  • description
  • 版本、工具权限、依赖等
• 核心执行流程
  • 触发条件：明确何时用/不用
  • 主干流程（≤500 行）
  • 输出规范：格式、结构、质量标准
  • 关键约束：必须遵守的规则

引用文件（references/）应放内容.

核心原则：详细、低频、大段、可独立拆分

1. 详细清单/规范
2. 大段参考资料
3. 复杂示例/模板
4. 扩展/可选流程

什么时候放SKILL.md、什么时候放引用文件、什么时候放脚本？

Skills 与Tools 的本质关系

• Skills约束Tools，Skills通过allowed-tools 约束Tools，实现最小权限原则

• read、Grep、Glob、Write、Edit、Bash

• read，含义：bash 内置命令，从键盘 / 输入读取内容，存到变量里

• grep, 含义：命令行工具，在文本里搜索关键词（最常用的搜索工具）

• Skills 编排 Tools。Skill 中的 scripts/ 目录存放的脚本，本质上是预编译的 Tool 调用序列。

# scripts/calculate_ratios.py
# 这个脚本 = Read(data_file) + 计算逻辑 + Print(results)
# Claude 不需要理解计算逻辑，只需要：
#   1. Bash("python scripts/calculate_ratios.py data.json")
#   2. 读取输出结果

• Tools 反哺 Skills。介绍的!command`` 语法展示了反向关系——Tools 的输出反哺 Skills 的上下文

---
name: pr-summary
description: Summarize changes in a pull request
---
## Context
- PR diff: !`gh pr diff`           # Tool 输出 → 注入 Skill 上下文
- Changed files: !`git diff --name-only`