update-skill

update-skill

本指南提供在此仓库中创建或更新技能的说明，涵盖所需结构、前置元数据以及技能的最佳实践。

快速开始

每个技能都是一个包含 SKILL.md 文件的目录，该文件包含 YAML 前置元数据和 Markdown 正文：

---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
---

# PDF 处理

## 何时使用此技能
当用户需要处理 PDF 文件时使用此技能...

## 如何提取文本
1. 使用 pdfplumber 进行文本提取...

## 如何填写表单
...

要求

前置元数据（必需）

每个 SKILL.md 必须以包含以下内容的 YAML 前置元数据开头：

• name：短横线命名标识符（仅限小写字母、数字、连字符）
  • 示例：add-feature-flag、pdf-processing、update-skill
• description：技能功能及使用场景的具体描述
  • 不能为空
  • 应包含技能发现的关键词
  • 以动作动词开头，明确说明技能完成的任务（例如“添加功能标志...”而不是“帮助处理功能...”），并立即跟上具体的用例或上下文（例如“在处理功能标志时使用”）
  • 使用第三人称（例如“添加功能标志...”而不是“我可以帮你添加...”）

编写有效的描述

描述字段对于技能发现至关重要。应同时包含技能的功能和使用时机。一些好的示例：

• git-commit：“通过分析 git 差异生成描述性的提交信息。在用户请求帮助编写提交信息或审查暂存更改时使用。”
• pdf-processing：“从 PDF 文件中提取文本和表格，填写表单，合并文档。在处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。”

避免使用模糊的描述，如“帮助处理代码”或“执行开发任务”。更多上下文，请参见 references/best-practices.md 中的“描述最佳实践”。

技能结构

Warp 技能中的典型章节：

1. 标题和简要摘要 – 清晰的标题和技能用途及主要用例的简洁概述。如有用，可链接到章节、参考文件或相关技能
2. 概述 – 关于技能用途的上下文（可选但常见），扩展摘要并提供更多细节和上下文
3. 主要内容 – 步骤、使用说明或工作流指导
4. 最佳实践 – 指南和建议（可选）
5. 示例/参考 PR – 真实示例的链接（可选）

根据技能需求保持结构灵活。简单的技能可以省略可选章节。

验证

可选地，使用 skills-ref 参考库验证你的技能：

skills-ref validate ./my-skill

这会检查你的 SKILL.md 前置元数据是否有效并遵循所有命名约定。如果未安装，请使用 WebSearch 工具获取此包的上下文。

主要内容最佳实践

• 关于什么构成好的主要内容的指导，请参见 references/best-practices.md 中的“简洁性原则”
• 格式化代码示例时，请参见 references/best-practices.md 中的“代码示例格式化”。

文件组织

• 简单技能（<=200 行）：将所有内容保留在 SKILL.md 中
• 复杂技能（>200 行）：将详细内容拆分到 references/ 子目录中
  • 从 SKILL.md 中通过清晰链接引用文件
  • 示例：“详细指导请参见 references/best-practices.md”

何时拆分内容

在以下情况下创建 references/ 子目录：

• SKILL.md 接近 200+ 行
• 技能涵盖多个领域或工作流，可以独立加载
• 详细的参考材料会干扰主要指令

仅将必要的工作流和过程性指令保留在 SKILL.md 中。将详细的参考材料、模式和大量示例移至 references/ 文件。

现有技能示例

关于结构和风格的参考：

• .agents/skills/add-feature-flag/SKILL.md - 多步骤工作流，步骤清晰有序
• .agents/skills/remove-feature-flag/SKILL.md - 包含搜索命令的清理工作流

最佳实践

详细编写指导请参见 references/best-practices.md，包括：

• 渐进式披露模式
• 编写简洁有效的指令
• 代码示例格式化
• 应避免的常见反模式