SuperAPI AI 工具集

update-skill

编程与开发

查看项目

更新于 10-16 06:58

技能介绍

用途

update-skill 是一个用于在本仓库中创建或更新技能的指南。当需要编写新技能或修订技能结构时,可参考本指南。它围绕 SKILL.md 文件的生成、编辑与完善展开。

技能的基本结构

每个技能是一个目录,目录中包含一个 SKILL.md 文件,该文件由 YAML frontmatter 和 Markdown 正文组成。

示例格式:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

Frontmatter 要求(必需)

每个 SKILL.md 必须以 YAML frontmatter 开头,其中包含:

  • name:使用 kebab-case 的标识符,仅允许小写字母、数字和连字符。示例:add-feature-flag、pdf-processing、update-skill
  • description:具体描述技能做什么以及在何时使用。要求非空,应包含便于技能发现的关键词;以动作动词开头,清楚说明技能能完成什么(例如用 "Adds feature flags..." 而非 "Helps with features..."),并紧接着给出具体使用场景或上下文(例如 "Use when working with feature flags");使用第三人称书写(例如 "Adds feature flags..." 而非 "I can help you add...")。

撰写有效描述

description 字段对技能发现至关重要,需同时包含技能做什么和何时使用。示例:

  • git-commit:"Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."
  • pdf-processing:"Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

应避免 "Helps with code" 或 "Does development tasks" 这类模糊描述。更多内容参见 references/best-practices.md 中的 "Description Best Practices"。

技能结构

Warp 技能通常包含以下部分:

  1. 标题与简要摘要——清晰的标题,以及技能用途和主要使用场景的简要概述。如需要,可链接到章节、参考文件或相关技能。
  2. 概述——关于技能用途的背景信息(可选但常见),在摘要基础上补充更多细节和上下文。
  3. 主体内容——步骤、使用说明或工作流指导。
  4. 最佳实践——指南与建议(可选)。
  5. 示例 / 参考 PR——指向真实示例的链接(可选)。

结构可根据技能需要保持灵活,简单技能可省略可选部分。

验证

可选择使用 skills-ref 参考库验证技能:

skills-ref validate ./my-skill

该命令检查 SKILL.md 的 frontmatter 是否有效并遵循所有命名约定。若未安装,可使用 WebSearch 工具获取该包的上下文信息。

文件组织

  • 简单技能(不超过 200 行):全部内容放在 SKILL.md 中。
  • 复杂技能(超过 200 行):将详细内容拆分到 references/ 子目录。
  • 在 SKILL.md 中通过清晰链接引用参考文件,例如:"See references/best-practices.md for detailed guidance"。

何时拆分内容

出现以下情况时创建 references/ 子目录:

  • SKILL.md 接近 200 行以上
  • 技能覆盖多个可独立加载的领域或工作流
  • 详细参考材料会使主要指令变得杂乱

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

参考示例

结构与时序参考:

  • .agents/skills/add-feature-flag/SKILL.md——多步骤工作流,步骤顺序清晰
  • .agents/skills/remove-feature-flag/SKILL.md——带搜索命令的清理工作流

最佳实践

参见 references/best-practices.md 获取详细编写指导,包括:

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

限制

当前资料未说明该技能的平台支持范围、收费情况或版本要求,这些信息暂未提供。