Skill 基础概念
什么是 Skill？
Skill 是一段结构化的 AI 指令集，专门解决某个特定场景的问题。它存储为一个 SKILL.md 文件，包含你的方法论、工作流程和提示词逻辑。用户安装后，只需触发对应的斜杠命令或描述需求，Skill 就会按照你设计的逻辑驱动 AI 完成任务。
Skill 的文件结构
一个 Skill 由一个目录组成：
~/.clacky/skills/my-skill/
├── SKILL.md # 必需：核心指令文件
├── scripts/ # 可选：脚本文件（推荐 Ruby）
├── references/ # 可选：参考文档（按需加载）
└── assets/ # 可选：模板、图标等静态资源
SKILL.md 格式
每个 SKILL.md 由两部分组成：YAML Frontmatter（元数据） + Markdown 正文（指令）。
---
name: my-skill
description: '解决 XX 问题的 Skill。当用户提到 XX、YY、ZZ 时触发。'
disable-model-invocation: false
user-invocable: true
---
# My Skill
这里是 AI 的执行指令...
Frontmatter 字段说明
| 字段 | 说明 | 是否必需 |
|---|---|---|
name |
Skill 标识符，小写字母+数字+连字符，如 my-skill |
必需 |
description |
触发机制：描述用途 + 列出触发场景和关键词 | 必需 |
disable-model-invocation |
固定填 false（允许 AI 自动触发） |
必需 |
user-invocable |
固定填 true（在 WebUI 斜杠命令列表中显示） |
必需 |
argument-hint |
斜杠命令后的参数提示，如 <文件路径> |
可选 |
allowed-tools |
限制 Skill 可用的工具列表 | 可选 |
model |
指定使用的 AI 模型（留空则用默认模型） | 可选 |
注意：
description是触发机制的核心。AI 读取 description 来判断是否调用这个 Skill。描述要具体，把触发关键词都写进去。
description 的写法
description 决定 Skill 在什么情况下会被触发。写法上有两个要点：
- 说清楚 Skill 能做什么
- 列出触发场景和关键词，宁可多触发，不要少触发
# ❌ 太模糊，容易漏触发
description: 'Helps with writing'
# ✅ 具体清晰，触发准确
description: 'Helps write and polish professional emails and business documents.
Use when user wants to draft an email, revise a report, improve tone,
or needs help with any writing task — even if they just say "help me write".'
description 的值建议用单引号包裹，避免冒号等符号导致 YAML 解析失败。
加载机制（三级渐进）
Skill 采用渐进式加载，按需消耗上下文：
- 元数据（
name+description）— 始终在上下文中，约 100 字 - SKILL.md 正文 — Skill 触发时加载，建议控制在 500 行以内
- Bundled Resources（
references/、scripts/）— 按需加载，无大小限制
当 SKILL.md 接近 500 行时，把大块参考内容提取到 references/ 下，在正文中写明何时读取。
Skill 的存储位置
Clacky 按优先级从三个位置加载 Skill：
| 位置 | 路径 | 说明 |
|---|---|---|
| 项目级 | .clacky/skills/<name>/ |
仅当前项目可用 |
| 用户级 | ~/.clacky/skills/<name>/ |
所有会话可用（推荐） |
| 内置 | gem 内置 | 平台默认 Skill，无需安装 |
创作者发布到 OpenClacky 平台后，用户通过品牌安装链接安装，Skill 以加密形式分发到 ~/.clacky/skills/ 下。
好 Skill 的标准
- 聚焦：解决一个具体问题，而非万能助手
- 自包含：执行时无需用户提供额外背景
- 有门槛：包含只有你才有的行业洞察或方法论
- 易触发：description 写得足够具体，让 AI 能准确识别触发时机
Skill vs 普通提示词
| 普通提示词 | OpenClacky Skill | |
|---|---|---|
| 分发方式 | 手动复制粘贴 | 一键安装 |
| 加密保护 | 不支持 | 上传即加密 |
| 商业化 | 不支持 | License 授权收费 |
| 版本管理 | 手动 | 平台内置 |
| 触发方式 | 手动粘贴 | 斜杠命令 / AI 自动识别 |