name: skill-creator description: 创建有效Agent Skills的指南。当用户想要创建新技能（或更新现有技能）以扩展AI agent能力，集成专业知识、工作流或工具时使用。涵盖技能结构、YAML frontmatter、触发器配置和500行规则。 license: AGPL-3.0 metadata: triggers: type: domain enforcement: suggest priority: high keywords: - skill - skill-rules - SKILL.md - creating skill - writing skill intent-patterns: - “\b(how do|how does|explain)\b.?\bskill\b" - "\b(create|add|modify|build|write)\b.?\bskill\b” - “\bskill\b.*?\b(work|trigger|activate|system|structure|template|pattern)\b”

技能创建器

本技能提供遵循 Agent Skills 规范创建有效技能的指导。

关于技能

技能是模块化、自包含的包，通过提供专业知识、工作流和工具来扩展AI agent能力。可将它们视为特定领域或任务的“入门指南”——它们将通用agent转变为具备程序性知识的专业agent，而这是任何模型都无法完全掌握的。

技能提供的内容

专业工作流 - 针对特定领域的多步骤程序
工具集成 - 处理特定文件格式或API的指令
领域专业知识 - 公司特定知识、模式、业务逻辑
捆绑资源 - 用于复杂和重复任务的脚本、参考和资产

核心原则

简洁是关键

上下文窗口是公共资源。技能与其他所有agent需要的内容共享上下文窗口：系统提示、对话历史、其他技能的元数据和实际用户请求。

默认假设：agent已经非常智能。 只添加它没有的上下文。挑战每条信息：“agent真的需要这个解释吗？”和“这段文字是否物有所值？”

优先使用简洁示例而非冗长解释。

设置适当的自由度

将特异性级别与任务的脆弱性和变异性匹配：

高自由度（基于文本的指令）：当多种方法有效、决策依赖上下文或启发式指导方法时使用。

中等自由度（伪代码或带参数的脚本）：当存在首选模式、允许一些变化或配置影响行为时使用。

低自由度（特定脚本、少量参数）：当操作脆弱易错、一致性至关重要或必须遵循特定顺序时使用。

技能结构

每个技能由必需的SKILL.md文件和可选捆绑资源组成：

skill-name/
├── SKILL.md（必需）
│   ├── YAML frontmatter 元数据（必需）
│   │   ├── name:（必需）
│   │   ├── description:（必需）
│   │   └── metadata.triggers:（可选，用于自动激活）
│   └── Markdown 指令（必需）
└── 捆绑资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash等）
    ├── references/       - 旨在根据需要加载到上下文中的文档
    └── assets/           - 输出中使用的文件（模板、图标、字体等）

SKILL.md Frontmatter

每个SKILL.md必须有包含必需和可选字段的YAML frontmatter：

字段	必需	描述
`name`	是	最多64字符。仅限小写字母、数字、连字符。必须与目录名匹配。
`description`	是	最多1024字符。描述技能功能和使用时机。
`license`	否	许可证名称或指向捆绑许可证文件的引用。
`compatibility`	否	最多500字符。环境要求（目标产品、系统包等）。
`metadata`	否	用于附加元数据的任意键值映射。
`allowed-tools`	否	预批准工具的空格分隔列表。（实验性）

触发器配置（metadata.triggers）

技能可以在 metadata.triggers 字段中定义自动激活触发器：

metadata:
  triggers:
    type: domain           # “domain”（建议性）或“guardrail”（强制执行）
    enforcement: suggest   # “suggest”、“warn”或“block”
    priority: high         # “critical”、“high”、“medium”或“low”
    keywords:              # 精确子串匹配（不区分大小写）
      - error
      - Result
      - error-stack
    intent-patterns:        # 用于意图检测的正则表达式模式
      - "\\b(handle|create)\\b.*?\\berror\\b"
      - "\\berror\\b.*?\\bhandling\\b"
    files:                  # 可选：基于文件的触发器
      include:
        - "**/src/**/*.rs"
      exclude:
        - "**/*.test.rs"
      content:
        - "use error_stack"

触发器类型：

keywords：用户提示中的不区分大小写子串匹配
intent-patterns：检测用户意图的正则表达式模式（使用 \\b 表示单词边界，.*? 表示非贪婪匹配）
files.include：文件路径的glob模式
files.exclude：排除的glob模式（例如，测试文件）
files.content：匹配文件内容的正则表达式模式

执行级别：

suggest：技能建议出现但不阻止执行
warn：显示警告但允许继续
block：要求在使用技能后才能继续（护栏）

捆绑资源（可选）

脚本（`scripts/`）

用于需要确定性可靠性或反复重写任务的可执行代码（Python/Bash等）。

何时包含：当相同代码被反复重写或需要确定性可靠性时
示例：用于PDF旋转任务的 scripts/rotate_pdf.py
优点：令牌高效、确定性，可能无需加载到上下文即可执行

参考资料（`references/`）

旨在在工作时加载到上下文中的文档和参考材料。

何时包含：用于agent应参考的文档
示例：金融模式的 references/finance.md，API规范的 references/api_docs.md
最佳实践：如果文件较大（>1万字），在SKILL.md中包含grep搜索模式

资产（`assets/`）

不旨在加载到上下文中，而是在输出中使用的文件。

何时包含：当技能需要用于最终输出的文件时
示例：品牌资产的 assets/logo.png，模板的 assets/template.pptx

渐进披露设计原则

技能使用三级加载系统以高效管理上下文：

元数据（名称+描述） - 始终在上下文中（约100字）
SKILL.md 主体 - 当技能触发时（推荐<5000字）
捆绑资源 - 根据需要（无限）

保持SKILL.md主体在500行以内。接近此限制时，将内容分割到单独文件中。

模式：带参考资料的高级指南

# PDF处理

## 快速开始
使用pdfplumber提取文本：[代码示例]

## 高级功能
- **表单填写**：完整指南见 [FORMS.md](references/FORMS.md)
- **API参考**：所有方法见 [REFERENCE.md](references/REFERENCE.md)

模式：领域特定组织

bigquery-skill/
├── SKILL.md（概述和导航）
└── references/
    ├── finance.md（收入、计费指标）
    ├── sales.md（机会、管道）
    └── product.md（API使用、功能）

技能创建过程

步骤1：通过具体示例理解技能

要创建有效技能，清晰理解技能将如何使用的具体示例：

“技能应支持哪些功能？”
“能给出一些使用此技能的示例吗？”
“用户说什么会触发此技能？”

步骤2：规划可重用技能内容

分析每个示例以确定哪些脚本、参考资料和资产会有帮助：

脚本：反复重写的代码（例如，scripts/rotate_pdf.py）
资产：样板模板（例如，前端项目的 assets/hello-world/）
参考资料：模式和文档（例如，references/schema.md）

步骤3：初始化技能

从头创建新技能时，运行init命令：

yarn agents:skill-management init <skill-name>

该命令在 .claude/skills/ 中创建技能目录，包含SKILL.md模板和示例资源目录。

步骤4：编辑技能

编写Frontmatter

---
name: my-skill
description: 描述技能功能和使用时机。包括触发关键词。
license: Apache-2.0
metadata:
  triggers:
    type: domain
    enforcement: suggest
    priority: medium
    keywords:
      - keyword1
      - keyword2
    intent-patterns:
      - "\\b(create|add)\\b.*?\\bsomething\\b"
---

描述最佳实践：

包括技能功能和特定触发/上下文
在此处包括所有“使用时机”信息——主体仅在触发后加载
最多1024字符

编写主体

编写使用技能的指令。保持在500行以内。

步骤5：生成和验证技能规则

创建/修改技能后，验证并重新生成skill-rules.json：

yarn agents:skill-management validate
yarn agents:skill-management generate-skill-rules

步骤6：测试技能

使用特定提示测试：

echo '{"session_id":"test","prompt":"你的测试提示","cwd":"."}' | \
  yarn workspace @local/claude-hooks run:skill

调试匹配逻辑：

echo '{"session_id":"test","prompt":"你的测试提示","cwd":"."}' | \
  yarn workspace @local/claude-hooks dev:skill

参考文件

有关特定主题的详细信息，见：

references/workflows.md：顺序和条件工作流模式
references/output-patterns.md：一致输出的模板和示例模式
references/patterns-library.md：用于触发器的即用正则表达式和glob模式
references/troubleshooting.md：技能激活问题调试指南

测试清单

[ ] 技能文件创建在 .claude/skills/{name}/SKILL.md
[ ] 适当的frontmatter，包含名称和描述
[ ] 在 metadata.triggers 中配置触发器
[ ] skill-rules.json 重新生成
[ ] 使用真实提示测试关键词
[ ] 使用变体测试意图模式
[ ] SKILL.md 在500行以内
[ ] 如有需要，创建参考文件