Agent Skills 最佳实战：EP02 渐进式加载与多文件组织

运维有术

发布于 2026-01-27 15:02:38

1790

🚩 2026 年「术」系列实战文档 X 篇原创计划第 5 篇 Agent Skills 最佳实战「2026」系列第 4 篇
大家好，欢迎来到 术哥无界 ShugeX ｜运维有术。我是术哥，一名专注于 AI编程、AI智能体、Agent Skills、MCP、云原生、Milvus 向量数据库的技术实践者与开源布道者！ Talk is cheap, let's explore。无界探索，有术而行。

上篇回顾

上一篇我们聊了 Skill 的基础用法：一个 SKILL.md 文件搞定一切。 但你可能已经发现一个问题：当 Skill 变复杂了，全塞在一个文件里就有点乱了。

比如你想做一个周报生成器，需要：

一套固定的报告模板
一个收集数据的脚本
一份格式规范说明

全写在 SKILL.md 里？那文件得有多长。

今天我们就来解决这个问题：如何组织多文件资源，让 Skill 既强大又整洁。

不想看文档可以看视频：

Skill 其实是个目录

上篇我们创建的 Skill 是这样的：

~/.claude/skills/commit-message/
└── SKILL.md

但 Skill 的完整形态其实是一个目录，可以包含多个文件：

~/.claude/skills/my-skill/
├── SKILL.md           # 必需：主指令文件
├── templates/         # 可选：模板文件
│   └── report.md
├── scripts/           # 可选：可执行脚本
│   └── gather-data.py
└── resources/         # 可选：参考资料
    └── style-guide.md

SKILL.md 是入口，其他文件按需加载。

渐进式加载：省 token 的秘密

你可能会担心：文件多了，会不会把上下文窗口撑爆？

不会。Claude Code 用了一套聪明的加载机制：

层级	内容	加载时机
Level 1	name + description	会话启动时，约 100 tokens
Level 2	SKILL.md 完整内容	Claude 判断需要用这个 Skill 时
Level 3	模板、脚本等附加文件	真正用到时才读取

这意味着你可以放心创建很多 Skill，装很多附加文件：只有真正用到的才会消耗上下文。

如何引用外部文件

在 SKILL.md 里引用其他文件很简单，用 Markdown 链接就行：

## 模板
生成报告时，请参考 [report-template.md](./templates/report-template.md) 的格式。

## 参考资料
详细的格式规范见 [style-guide.md](./resources/style-guide.md)。

Claude 看到这些链接后，会在需要时自动读取对应文件。

如果是脚本，可以这样写：

## 可用脚本

在生成报告前，先运行数据收集脚本：

./scripts/gather-data.py --week current

脚本会输出本周的工作数据，供后续使用。

实战：创建周报生成 Skill

说了这么多，不如直接上手。我们来创建一个完整的周报生成 Skill。

第一步：创建目录结构

mkdir -p ~/.claude/skills/weekly-report/templates
mkdir -p ~/.claude/skills/weekly-report/scripts

第二步：创建模板文件

在 templates/report-template.md 中写入：

# 周报 - {{日期范围}}

## 本周完成

### 主要工作
-

### 代码提交
-

## 遇到的问题

| 问题 | 状态 | 解决方案 |
|------|------|----------|
|      |      |          |

## 下周计划

1.
2.
3.

## 需要协调的事项

-

这个模板定义了周报的标准结构。Claude 生成周报时会按这个格式来。

第三步：创建数据收集脚本

在 scripts/gather-data.sh 中写入：

#!/bin/bash
# 收集本周 Git 提交记录

echo"=== 本周 Git 提交统计 ==="
echo""

# 获取本周一的日期
if [[ "$OSTYPE" == "darwin"* ]]; then
    MONDAY=$(date -v-monday +%Y-%m-%d)
else
    MONDAY=$(date -d "last monday" +%Y-%m-%d)
fi

echo"统计范围: $MONDAY 至今"
echo""

# 统计提交数量
echo"提交数量:"
git log --since="$MONDAY" --oneline 2>/dev/null | wc -l

echo""
echo"提交详情:"
git log --since="$MONDAY" --pretty=format:"- %s (%ad)" --date=short 2>/dev/null

echo""
echo"=== 统计完成 ==="

别忘了加执行权限：

chmod +x ~/.claude/skills/weekly-report/scripts/gather-data.sh

第四步：创建主指令文件

在 SKILL.md 中写入：

---
name: weekly-report
description: 生成团队周报。当用户说"写周报"、"生成本周总结"、"weekly report"时自动触发。
---

# 周报生成器

## 工作流程

1. 首先运行数据收集脚本获取本周工作数据：
   ./scripts/gather-data.sh

2. 读取 [report-template.md](./templates/report-template.md) 获取报告格式

3. 根据收集到的数据和用户补充的信息，按模板格式生成周报

4. 输出完整的 Markdown 格式周报

## 注意事项

- 日期范围自动计算为本周一到今天
- 如果 Git 仓库不存在，跳过代码提交统计
- 用户可以口头补充模板中没有的内容
- 保持简洁，不要写废话

第五步：测试效果

打开 Claude Code，在任意 Git 项目中说：

帮我写周报

Claude 会：

自动识别并加载 weekly-report Skill
运行脚本收集 Git 提交数据
按模板格式生成周报
可能会问你一些补充信息（比如遇到了什么问题）

整个过程不需要你解释周报格式，不需要你手动统计提交记录。

几个进阶技巧

1. 用 allowed-tools 限制权限

有时候你希望 Skill 只能读取文件，不能修改。可以在 frontmatter 里加限制：

---
name: code-review
description: 代码审查助手
allowed-tools: Read, Grep, Glob
---

这样 Claude 在使用这个 Skill 时，只能用 Read、Grep、Glob 这三个工具，不能执行 Write 或 Bash。

适合做只读的审计类 Skill。

2. 用 $ARGUMENTS 接收参数

如果你想让 Skill 接收动态参数，可以用 $ARGUMENTS 占位符：

---
name: fix-issue
description: 修复 GitHub issue
argument-hint: [issue-number]
---

请修复 GitHub issue #$ARGUMENTS。

步骤：
1. 读取 issue 描述
2. 分析问题原因
3. 实现修复
4. 编写测试

调用时输入 /fix-issue 123，Claude 收到的就是 请修复 GitHub issue #123。

3. 禁用自动触发

有些 Skill 你只想手动调用，不想让 Claude 自动判断。加上这个配置：

---
name: dangerous-operation
description: 执行危险操作
disable-model-invocation: true
---

这样只有你手动输入 /dangerous-operation 时才会触发。

目录组织的最佳实践

用了一段时间后，我总结了几条经验：

1. SKILL.md 保持精简

主指令文件控制在 500 行以内。太长的内容拆到单独文件里，用链接引用。

2. 单一职责

一个 Skill 只做一件事。想做周报又想做日报？拆成两个 Skill。

3. 自包含

Skill 应该自给自足，不要假设用户知道某些上下文。把必要的说明都写清楚。

4. 版本控制

项目级的 Skill（放在 .claude/skills/）建议提交到 Git。这样团队成员都能用，改动也有记录。

完整目录结构参考

一个成熟的 Skill 目录可能长这样：

~/.claude/skills/weekly-report/
├── SKILL.md              # 主指令（必需）
├── templates/            # 模板文件
│   ├── report-template.md
│   └── summary-template.md
├── scripts/              # 可执行脚本
│   ├── gather-data.sh
│   └── send-email.py
├── resources/            # 参考资料
│   ├── style-guide.md
│   └── examples/
│       ├── good-report.md
│       └── bad-report.md
└── README.md             # 给人看的说明（可选）