Community写作与编辑github.com

编写Agent技能

设计、起草、修订或审计可复用的AI Agent技能和SKILL.md指令包。适用于创建或改进技能的适用范围、触发描述、工作流程、支持性参考资料或脚本、安全边界及评估;根据宿主Agent和实际任务对技能进行定制。

编写Agent技能 是什么?

该技能旨在帮助开发者或AI Agent用户系统性地创建、修订和审计可复用的AI Agent技能包(包括SKILL.md文件)。它提供了一个完整的工作流程:从定义技能的触发条件、输入输出契约,到起草结构清晰的SKILL.md文档,再到通过实际案例测试和迭代改进。核心价值在于确保技能指令包不仅可运行,而且贴合宿主Agent的能力和实际任务需求,避免生成模糊或不可操作的指令。该技能支持在任何需要编写或维护Agent技能的平台上使用,例如Claude Code、Cursor或Codex等,特别强调指令的精确性、安全性边界和可测试性,并鼓励使用参考文件来减少主文档的冗余。通过遵循其定义的“交付检查”步骤,用户能确保最终产出的技能文件完整、内部一致且经过初步验证,从而提高Agent执行的可靠性和效率。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rafik-mikhail/write-agent-skill/tree/main

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

编写Agent技能 是做什么的?

目标

交付一个可供Agent直接运行的指令包,用于完成一项连贯、可复用的工作。将其立足于用户的任务、示例、工具环境、已有工件和修正反馈。如果没有真实示例可用,请标注假设并起草最小可测试指令,而不是编造特定产品的API。完成并呈现实际所需的技能,而不是仅提供计划、进度报告或批评。

定义契约

  1. 说明触发条件:应激活此技能的任务和输入,以及不应激活的相邻请求。将 description 写成一个简洁的路由规则,指明它做什么以及何时使用。
  2. 说明必需和可选的输入、Agent允许的权限、预期输出以及完成的定义。在交接处解决与相邻技能的重叠问题;不要仅仅因为它们共享一个主题就合并不同的阶段。
  3. 标记哪些行为是强制性的安全或正确性门控,哪些是默认启发式规则,哪些是可选的增强功能。指令不能强制执行运行时权限:请使用平台控件来管理文件系统、网络和工具访问。

起草 SKILL.md

使用YAML frontmatter,其中 name 为小写连字符形式并与文件夹名匹配,description 为具体描述。遵循宿主平台的格式和能力要求;不要假设可选元数据或 allowed-tools 能跨平台强制实施访问控制。

保持主体简洁:包括工作内容和边界、输入、决策过程、停止/失败处理、输出契约以及不明显的陷阱。提供一个默认路径,而不是一系列等同的选项。对于脆弱操作给出精确步骤;在上下文选择中为合理判断留出余地。避免在每个部分重复相同的禁令,或将一次性任务的答案嵌入为通用流程。

将大型领域参考资料移至专门的 references/ 文件,并明确告知Agent何时阅读它们。仅在确认了其运行时依赖项和验证行为后,才为重复的确定性工作添加可复用的脚本。确保参考资料可从 SKILL.md 直接访问,并且不要声称某草稿已被安装、执行或验证,而事实并非如此。

测试和修订

从2-3个代表性案例开始,包括一个边缘案例;当技能处理不可信内容或具有重要边界时,添加负触发和对抗性案例。在有和没有该技能的情况下,或针对之前的草稿,运行全新的会话。对可观察的输出和工具行为进行评分,而不是指令听起来有多优美。检查跟踪记录,查找不必要的步骤、遗漏的证据、误激活和范围蔓延。对于机械性检查使用代码;让人工审查实质性判断。移除那些增加成本但未能防止实际失败的指令。

交付检查

在回应之前,验证所请求的完整工件确实存在且内部一致。当用户要求完整的Markdown时,交付当前完整的 SKILL.md,而不是补丁片段。如果正在创建文件,请验证它存在并包含完整的草稿;如实报告未经测试的状态。简要说明更改了什么以及剩余的验证需求。不要在没有明确请求的情况下,将一个技能请求转变为不相关的套件。

相关技能