Agent skill

目录

• SKILL.md 文件
  • 元数据
  • 指令
• 工作原理
• 高级用法
  • Reference
  • scripts
• 渐进式披露
• Agent skill VS MCP
• allowed-tool
• disallowed-tools

1. my-skill 文件夹格式

SKILL.md 文件

元数据

kiro 中的字段说明：

指令

这一部分在详细描述模型需要遵循的详细规则

工作原理

这里以claude为例子：

• claude 只是将 SKILL.md 中的元数据列表传输给大模型，大模型来选择使用哪个skill，然后才加载这个skill的全部信息给LLM， 也就是按需加载 ， 因此可以节省很多token

高级用法

Reference

在SKILL.md 文件中定义使用规则：

发现了这个文件：

scripts

1.定义规则

2.创建脚本

3.结果：

细节：
claude 只是申请执行这个文件，并没有读取这个文件，agent skill 里面的代码只会被执行，不会被读取，这就意味着，即使这个文件即使你写了一万行代码，被消耗的模型上下文的token也几乎是0
claude code 只关心脚本的运行方法和结果，不在意脚本的内容

渐进式披露

Agent skill VS MCP

allowed-tool

allowed-tools 是 SKILL.md 头部（frontmatter）里的一个字段，作用是：在这个 skill 运行期间，列在里面的工具自动放行，不再弹权限确认。相当于一份“只在该 skill 执行时生效的临时白名单”，不改动  
  settings.json，skill 结束后即失效。
     
  语法
  
  写在 frontmatter 里，逗号分隔多条规则，规则格式和 settings.json 的权限规则完全相同：
     
  ---
  name: db-report
  description: 查询数据库并生成报告
  allowed-tools: mcp__mysql__query, Write(reports/**), Bash(npm run lint:*)
  ---

  支持的写法：

  ┌──────────────────────────────────┬───────────────────────────────────────┐
  │               写法               │                 含义                  │
  ├──────────────────────────────────┼───────────────────────────────────────┤
  │ Write                            │ 该工具的所有调用都放行                │
  ├──────────────────────────────────┼───────────────────────────────────────┤
  │ Bash(git log:*)                  │ 只放行匹配前缀的命令（:* 是前缀匹配） │
  ├──────────────────────────────────┼───────────────────────────────────────┤
  │ Read(./data/**) / Edit(docs/**)  │ 只放行匹配路径的读写                  │
  ├──────────────────────────────────┼───────────────────────────────────────┤
  │ mcp__mysql__query                │ 放行某个 MCP 工具                     │
  ├──────────────────────────────────┼───────────────────────────────────────┤
  │ WebFetch(domain:api.example.com) │ 只放行指定域名                        │
  └──────────────────────────────────┴───────────────────────────────────────┘

  和前面聊的 allow 白名单的关系
 
  两者是同一套规则语法、不同的生效范围：

  - settings.json 的 permissions.allow → 全局/项目级永久生效；
  - skill 的 allowed-tools → 只在这个 skill 运行的那段时间生效。

  所以它是比加全局白名单更收敛的方案：比如你那个性能测试报告的 skill，如果里面要查数据库、写 HTML 文件，可以在它的 frontmatter 里写 allowed-tools: mcp__xxx__query,
  Write(...)——平时手动查库照样弹确认，只有走这个 skill 的固定流程时免确认。

  两个语义要点

  1. 它是“授予”，不是“限制”。不在列表里的工具并不会被禁用，只是回到正常确认流程；列表内的才是免确认。
  2. 生效范围仅限本次 skill 调用，不会累积、不会写入任何配置。

  安全提醒

  allowed-tools 本质是skill 作者给自己预授权。所以：

  - 自己写的 skill 随便加，没问题；
  - 别人的 skill（尤其 clone 下来的项目里带的 .claude/skills/）加了 allowed-tools: Bash 之类的宽泛规则，就意味着它运行时可以不经过你确认执行任意命令——装之前看一眼它的 frontmatter
  和正文，确认没夹带危险授权。

  验证方式很简单：给某个 skill 加上规则后触发一次，看对应工具是否还弹确认即可。

disallowed-tools

disallowed-tools 是 allowed-tools 的镜像：skill 运行期间，匹配到的工具直接拒绝调用——不是转成弹确认，而是模型根本调不动，调用会收到权限拒绝。同样写在 SKILL.md 的 frontmatter 里，只在该    
  skill 执行期间生效，结束后恢复原来的权限状态。
     
  语法 与权限规则同一套语法，逗号分隔：

  ---
  name: code-readonly
  description: 只读分析模式
  disallowed-tools: Edit, Write, NotebookEdit, Bash(rm:*), Bash(git commit:*)
  ---

  裸工具名（Edit）禁整类调用；带限定符（Bash(rm:*)）只禁匹配的命令。

  与 allowed-tools 的对比

  ┌──────────────┬────────────────────────────┬────────────────────────────┐
  │              │       allowed-tools        │      disallowed-tools      │
  ├──────────────┼────────────────────────────┼────────────────────────────┤
  │ 匹配的工具   │ 免确认，直接放行           │ 直接拒绝，模型收到 denied  │
  ├──────────────┼────────────────────────────┼────────────────────────────┤
  │ 不匹配的工具 │ 不禁用，走正常确认流程     │ 不受影响，走正常流程       │
  ├──────────────┼────────────────────────────┼────────────────────────────┤
  │ 本质         │ 临时授予（做减法：少打扰） │ 临时剥夺（做加法：硬约束） │
  └──────────────┴────────────────────────────┴────────────────────────────┘

两条规则可以共存于同一个 skill；若某个工具同时匹配两边，deny 优先。而且 skill 内的 disallow 优先级高于 settings.json 里的全局 allow——即使某工具已在全局白名单，skill 里声明禁用照样调不动。

  典型用途：把“靠自觉”变成“物理护栏”

  最合适的例子就是你这项目里的 code-readonly skill。它目前是靠正文指令约束“禁止使用
  Edit、Write、NotebookEdit”——这依赖模型遵守指令，理论上存在被违反的可能（比如被文件内容里的注入指令带偏）。如果改成：

  ---
  name: code-readonly
  description: 只读保护模式……
  disallowed-tools: Edit, Write, NotebookEdit
  ---

  就变成 harness 层强制执行：工具调用在系统层被直接拒绝，模型想违规也没有入口。指令约束（防 Bash 间接写文件等）可以保留，两者互补。

  一个局限

  它只能“整类禁”或“按模式禁”，表达不了“这个工具只允许其中一部分操作”的白名单逻辑。比如“Bash 允许 ls/cat 但禁
  rm”，只能靠逐条列举危险模式（Bash(rm:*)、Bash(tee:*)……），枚举不全就有漏网。这类精细控制还是得反向用 allowed-tools 来配。

上文提到的code-readonly skill

---
name: code-readonly
description: 只读保护模式。凡是在本项目中查看、分析、讨论代码或数据的任务均适用——禁止创建、修改、删除任何文件。用户没有明确说"修改/写入/保存"时一律启用本规则。
---

# 只读保护规则

启用本 skill 后，在整个会话中严格遵守：

## 绝对禁止

- 禁止使用 Edit、Write、NotebookEdit 工具
- 禁止通过 Bash 间接改文件或改环境，包括但不限于：
  - `rm` / `mv` / `cp` / `tee` / `sed -i` / `echo > 文件` / `>` 重定向写文件
  - `git commit` / `git push` / `git checkout` / `git reset` / `git rebase` / `git clean` 等改动仓库的操 作
  - `npm install` / `pip install` 等改环境的操作

## 允许

- Read、Glob、Grep 等只读工具
- 只读命令：`ls`、`cat`、`head`、`tail`、`git status` / `git diff` / `git log`、`wc` 等

## 输出方式

- 给出修改建议时，把改动内容以代码块形式直接贴在回复里，不要写入文件
- 确实需要生成文件（如报告）时，先向用户确认允许写入及目标路径，得到明确同意后才创建
- 任何不确定是否有副作用的命令，先说明意图再执行

其他文档：

https://zhuanlan.zhihu.com/p/1987456533315999135
https://claudecn.com/docs/agent-skills/