mcpField
W
write-a-skill

write-a-skill

github.com/akillnessAgent 工作流5363 次安装1 天前更新
代码仓库

关于 write-a-skill

write-a-skill 是用于编写有文档、可复用 Agent 技能的指南，面向技能作者。它涵盖需求梳理、结构化 SKILL.md 起草，以及触发条件、边界和配套文件的审查。

主要功能

  1. 01需求梳理
  2. 02结构化起草 SKILL.md
  3. 03配套文件规划建议
  4. 04触发条件与边界审查
  5. 05技能质量检查清单

适用场景

  1. 01将工作流整理为可复用技能
  2. 02创建新的 Agent 能力
  3. 03记录模式以便发现和调用技能

安装

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

$npx skills add https://github.com/akillness/jeo-skills --skill write-a-skill

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

详细介绍

编写 Skill

创建结构完善且文档齐全的 Agent 技能。

上游状态

已被上游的 writing-for-agents 取代。由于 find-skills、upskill、solo-skills 和 openocta 仍会路由到此处，因此予以保留。

何时使用此技能

  • 将工作流规范为可复用、可共享的技能
  • 从头构建新的 Agent 能力
  • 记录现有模式，方便 Agent 发现和使用

关键设计原则

Agent 在决定加载哪项技能时，唯一能看到的就是 description 字段。

编写 description 时：

  • 清楚说明此技能的用途
  • 包含明确的触发条件：“Use when [context]”
  • 最多 1024 个字符
  • 描述要足够准确，让 Agent 知道是否应启用此技能

流程

阶段 1 — 收集需求

了解：

  • 此技能要规范哪项任务或工作流？
  • 触发条件是什么（Agent 应在何时启用此技能）？
  • 此技能的边界是什么（它不处理什么）？
  • 此技能应适用于哪些平台？
  • 此技能是否与现有技能重叠？
阶段 2 — 起草技能

创建 SKILL.md 作为核心文件。保持在 100 行以内。

出现以下情况时，拆分为其他文件：

  • SKILL.md 超过约 100 行
  • 内容涉及用户并非总是需要的不同领域
  • 示例会使核心说明显得臃肿

支持的辅助文件：

  • REFERENCE.md — 详细参考内容
  • EXAMPLES.md — 具体示例
  • scripts/ — 确定性实用脚本
阶段 3 — 与用户审核

提交草稿。确认：

  • Description 是否能准确地在适当的请求中触发？
  • 说明是否清晰完整？
  • 边界是否能防止误用？
  • 是否需要辅助文件，还是 SKILL.md 已足够？

SKILL.md 模板（jeo-skills 格式）

---
name: skill-name
description: >
  One-paragraph description of what this skill does and when to use it.
  Include trigger conditions: "Use when [specific context]."
allowed-tools: Read Grep Glob Bash Write Edit
compatibility: >
  Platform and context compatibility notes. What it pairs with.
metadata:
  tags: tag1, tag2, tag3, tag4
  platforms: Claude, ChatGPT, Gemini, Codex
  version: "1.0"
  source: your-github/repo
---

# Skill Name

Brief intro paragraph.

## When to use this skill

- Condition 1
- Condition 2

## When not to use this skill

- Route-out 1 → use `other-skill`
- Route-out 2 → use `other-skill`

## Instructions

[Core instructions here]

质量检查清单

  • Description 不超过 1024 个字符
  • Description 包含“Use when [context]”触发语句
  • SKILL.md 不超过 100 行（或有充分理由进行拆分）
  • “何时不使用”部分会将用户引导至特定技能
  • metadata.tags 涵盖便于发现的关键词
  • Description 中不包含实现细节（这些内容应放在正文中）

示例

  • 示例：先将此技能应用于小范围，验证通过后再扩大到完整范围。

最佳实践

  • 保持输出具有确定性且可审计。
  • 优先采用小幅、可逆的更改，避免大范围的高风险编辑。
  • 明确记录假设。

参考资料

  • 项目标准：.agent-skills/skill-standardization/SKILL.md
  • 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh

评论

支持 Markdown