mcpField
U
update-skill

update-skill

github.com/warpdotdevAgent 工作流63628.4k 次安装1 周前更新
代码仓库

关于 update-skill

指导在代码库中创建或更新技能，涵盖 `SKILL.md` 的 frontmatter、描述、结构和文件组织。也介绍使用 `skills-ref` 进行可选验证。

主要功能

  1. 01YAML frontmatter 要求
  2. 02技能描述编写指引
  3. 03建议的文档结构
  4. 04拆分参考文件的规则
  5. 05可选的 `skills-ref` 验证

适用场景

  1. 01从头创建代码库技能
  2. 02修改技能描述或文档结构
  3. 03判断何时将细节移至参考文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/warpdotdev/common-skills --skill update-skill

安装后在 Claude Code 中输入/update-skill确认已加载。

附带文件references/best-practices.md

详细介绍

update-skill

本指南介绍如何在此仓库中创建或更新技能，涵盖技能所需的结构、frontmatter 和最佳实践。

快速入门

每个技能都是一个目录，其中包含带有 YAML frontmatter 和 Markdown 正文的 SKILL.md 文件：

---
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...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

要求

Frontmatter（必需）

每个 SKILL.md 都必须以 YAML frontmatter 开头，其中包含：

  • name：短横线分隔的标识符（仅限小写字母、数字和连字符）
    • 示例：add-feature-flag、pdf-processing、update-skill
  • description：具体说明技能的功能及适用场景
    • 不能为空
    • 应包含有助于发现技能的关键词
    • 以动作动词开头，清楚说明技能的作用（例如，“添加功能标志……”而不是“协助处理功能……”），并紧接着说明具体用例或场景（例如，“在处理功能标志时使用”）
    • 使用第三人称（例如，“添加功能标志……”而不是“我可以帮你添加……”）
编写有效的描述

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 的 frontmatter 是否有效，以及是否遵循所有命名约定。如果尚未安装，请使用 WebSearch 工具了解此软件包。

主要内容最佳实践
文件组织
  • 简单技能（<=200 行）：将所有内容放在 SKILL.md 中
  • 复杂技能（>200 行）：将详细内容拆分到 references/ 子目录中

何时拆分内容

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

  • SKILL.md 接近 200 行或超过 200 行
  • 技能涵盖多个可独立加载的领域或工作流
  • 详细的参考资料会使主要说明显得臃肿

SKILL.md 中仅保留必要的工作流和操作说明。将详细参考资料、架构和大量示例移至 references/ 文件。

现有技能示例

结构和风格参考：

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

最佳实践

请参阅 references/best-practices.md，了解详细的编写指南，包括：

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

评论

支持 Markdown