SKILL.md 字段参考

每个 Skill 的核心是一个 SKILL.md 文件。YAML frontmatter 控制 Skill 的行为和触发方式，frontmatter 之后的正文是给 Agent 的指令内容。

完整结构

---
name: my-skill
description: 一句话描述触发场景
# ... 其他字段
---

# 指令正文

告诉 Agent 怎么执行这个 Skill 的具体内容。

name: my-skill

Skill 的唯一标识符。用于目录命名和内部引用。通常用连字符分隔的小写形式（kebab-case）。

description: 当用户想要分析竞品或做市场调研时触发。也可通过 /competitor-analysis 直接调用。

最关键的字段。 Agent 读取这段描述来判断当前用户请求是否应该触发这个 Skill。

写好 description 的原则：
- 描述触发场景，而不是功能本身
- 列举典型的触发短语（中英文都要写）
- 如果支持斜杠命令，注明格式（如 /my-skill）
- 越具体越好——模糊的描述容易导致误触发或漏触发

fork_agent: true

设为 true 时，Skill 在独立的子 Agent 中执行，与主会话的工具调用隔离。

适用场景：
- Skill 有自己的 forbidden_tools 需要隔离
- 需要在不污染主对话历史的情况下执行复杂操作
- 使用 web_fetch 抓取数据后再返回结果

forbidden_tools:
  - write
  - edit
  - safe_shell

列出这个 Skill 不允许使用的工具。通常配合 fork_agent: true 使用，给只读型 Skill 加安全约束。

auto_summarize: true

设为 true 时，Skill 执行完毕后自动生成摘要，压缩上下文。对执行步骤较多的长 Skill 有用。

user-invocable: false

设为 false 时，该 Skill 不会出现在用户可用的 Skill 列表中，也不能被用户直接调用。
通常用于平台内部的工具性 Skill，设计上只由其他 Skill 或系统触发。

默认：true（用户可见可调用）。

disable-model-invocation: true

设为 true 时，调用这个 Skill 时跳过模型推理，直接执行 Skill 的脚本逻辑（如果有）。用于纯脚本型 Skill，没有需要 LLM 参与的对话步骤。

argument-hint: "<github-repo-url>"

显示在 Skill 调用界面的参数提示，告诉用户应该传入什么参数。

allowed-tools:
  - web_fetch
  - file_reader

白名单：只允许这个 Skill 使用列出的工具，其余工具全部禁用。与 forbidden_tools（黑名单）互斥，二选一使用。

model: lite

指定执行这个 Skill 时使用的模型。可选值：
- lite — 使用配置中的 lite 模型（更快、更省钱）
- default — 使用默认模型

如果不设置，使用当前 Agent 的默认模型。

agent: general

指定执行这个 Skill 时使用的 Agent 配置文件（profile）。如果 Skill 需要与编码 Agent 不同的人设或行为规则，可以在这里切换。

context:
  - ~/.clacky/agents/SOUL.md
  - .clackyrules

执行 Skill 时额外注入到 prompt 的文件列表。可以是绝对路径、相对路径，或 glob 模式。

hooks:
  after_task:
    - command: ruby scripts/update_index.rb
      timeout: 30

Skill 执行完成后自动运行的 shell 命令。after_task 是目前唯一支持的 hook 点。

字段：
- command — 要运行的 shell 命令
- timeout — 超时秒数（可选）