mcpField
W
write-a-skill

write-a-skill

github.com/alirezarezvaniAgent 工作流29.0k393 次安装今天更新
代码仓库

关于 write-a-skill

write-a-skill 是面向 Agent 和技能创作者的技能编写指南，涵盖需求收集、起草与审阅，并提供检查清单工具及脚本和文件拆分建议。

主要功能

  1. 01三阶段技能编写流程
  2. 02SKILL.md 结构与模板
  3. 03描述和触发条件指南
  4. 04脚本与文件拆分准则
  5. 05自动化审阅检查清单

适用场景

  1. 01根据需求起草技能
  2. 02判断技能是否需要脚本
  3. 03使用前检查技能内容

安装

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

$npx skills add https://github.com/alirezarezvani/claude-skills --skill write-a-skill

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
companion_tooling.md
description_design_patterns.md
progressive_disclosure_principles.md
quality_gates_for_skills.md
scripts/
_skill_frontmatter.py
skill_description_validator.py
skill_review_checklist_runner.py
skill_structure_validator.py

详细介绍

编写技能

源自 Matt Pocock 的 write-a-skill（MIT）。原样保留 Matt 的表达风格和 3 阶段工作流。新增内容：验证工具 + 参考资料 + cs-* 封装器（见下文 工具 + 配套组件）。

流程

  1. 收集需求 - 询问用户：

    • 这项技能涵盖什么任务/领域？
    • 需要处理哪些具体用例？
    • 是否需要可执行脚本，还是只需要说明？
    • 是否需要包含任何参考资料？

  2. 起草技能 - 创建：

    • 包含简明说明的 SKILL.md
    • 如果内容超过 500 行，则创建额外的参考文件
    • 如果需要执行确定性操作，则创建实用脚本

  3. 与用户审核 - 呈现草稿并询问：

    • 这是否涵盖了你的用例？
    • 是否有遗漏或不清楚的内容？
    • 是否需要增加或减少某些部分的详细程度？

技能结构

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md 模板

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

描述要求

描述是你的 Agent 在决定加载哪项技能时能看到的唯一内容。它会与所有其他已安装技能一起显示在系统提示词中。Agent 会阅读这些描述，并根据用户的请求选择相关技能。

目标：提供足够的信息，让你的 Agent 知道：

  1. 这项技能提供什么能力
  2. 何时/为何触发它（具体关键词、上下文、文件类型）

格式：

  • 最多 1024 个字符
  • 使用第三人称
  • 第一句：说明它的作用
  • 第二句：“在[具体触发条件]时使用”

优秀示例：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

糟糕示例：

Helps with documents.

糟糕示例无法让你的 Agent 将这项技能与其他文档技能区分开来。

何时添加脚本

在以下情况下添加实用脚本：

  • 操作具有确定性（验证、格式化）
  • 会反复生成相同代码
  • 需要明确处理错误

与生成代码相比，脚本能节省令牌并提高可靠性。

何时拆分文件

在以下情况下拆分为单独的文件：

  • SKILL.md 超过 100 行
  • 内容涉及不同领域（金融与销售模式）
  • 很少需要使用高级功能

审核清单

起草后，确认：

  • 描述包含触发条件（“在……时使用”）
  • SKILL.md 少于 100 行
  • 不含时效性信息
  • 术语一致
  • 包含具体示例
  • 参考资料最多一层深

工具 + 配套组件

验证工具 + cs-* 封装器与这项技能配套使用。通过程序检查全部 6 项审核清单内容：

python scripts/skill_review_checklist_runner.py path/to/skill-folder

参见 references/companion_tooling.md，了解工具目录、cs-skill-author persona agent 和 /cs-write-a-skill slash command。

知识来自文档，而非你的头脑时

这项技能基于你已有的专业知识编写。如果源内容是一本书、一个文档文件夹、一项标准或一批规范，请改用 engineering/book-to-skill ——它会将文档编译成知识库技能（核心框架 + 按需章节 + 术语表 + 模式 + 速查表），还可以将结果打包成插件。

/cs-book-to-skill <path|folder|glob> [skill-name]     # compile the source
/cs-book-to-plugin <compiled-skill-dir>               # wrap it as a plugin

经验法则：**先编写，再编译。**手写技能说明你希望 Agent 执行什么；编译生成的书籍技能则是 Agent 执行任务时查阅的参考资料。如果两者都有，它们就是两项技能，而不是一项。

版本： 1.0.0 源自： Matt Pocock（MIT）+ 本仓库的封装器

评论

支持 Markdown