write-a-skill
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWriting Skills
编写Skill
Process
流程
-
Gather requirements - ask user about:
- What task/domain does the skill cover?
- What specific use cases should it handle?
- Does it need executable scripts or just instructions?
- Any reference materials to include?
-
Draft the skill - create:
- SKILL.md with concise instructions
- Additional reference files if content exceeds 500 lines
- Utility scripts if deterministic operations needed
-
Review with user - present draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more/less detailed?
-
收集需求 - 向用户确认：
- 该Skill覆盖哪些任务/领域？
- 它需要处理哪些具体用例？
- 是否需要可执行脚本，还是仅需操作说明？
- 有哪些参考资料需要纳入？
-
起草Skill - 创建以下内容：
- 包含简洁说明的SKILL.md文件
- 若内容超过500行，需额外添加参考文件
- 若涉及确定性操作，需编写实用脚本
-
与用户审核 - 展示草稿并询问：
- 这份草稿是否覆盖了你的所有用例？
- 有没有遗漏或表述模糊的内容？
- 是否需要调整某些章节的详细程度？
Skill Structure
Skill结构
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.jsskill-name/
├── SKILL.md # Main instructions (required)
├── REFERENCE.md # Detailed docs (if needed)
├── EXAMPLES.md # Usage examples (if needed)
└── scripts/ # Utility scripts (if needed)
└── helper.jsSKILL.md Template
SKILL.md模板
md
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---md
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---Skill Name
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]
undefined[链接至独立文件：详见REFERENCE.md]
undefinedDescription Requirements
描述要求
The description is the only thing your agent sees when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
Goal: Give your agent just enough info to know:
- What capability this skill provides
- When/why to trigger it (specific keywords, contexts, file types)
Format:
- Max 1024 chars
- Write in third person
- First sentence: what it does
- Second sentence: "Use when [specific triggers]"
Good example:
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.Bad example:
Helps with documents.The bad example gives your agent no way to distinguish this from other document skills.
描述是Agent在决定加载哪个Skill时唯一会查看的内容，它会和其他已安装的Skill一起出现在系统提示词中。Agent会读取这些描述，并根据用户的请求选择相关的Skill。
目标：为Agent提供足够的信息，使其明确：
- 该Skill具备什么能力
- 何时/为何触发它（特定关键词、场景、文件类型）
格式：
- 最多1024个字符
- 使用第三人称撰写
- 第一句：说明该Skill的功能
- 第二句：“适用于[特定触发场景]”
优秀示例：
从PDF文件中提取文本和表格、填写表单、合并文档。适用于处理PDF文件或用户提及PDF、表单或文档提取的场景。反面示例：
帮助处理文档。反面示例没有给Agent提供区分该Skill与其他文档类Skill的依据。
When to Add Scripts
何时添加脚本
Add utility scripts when:
- Operation is deterministic (validation, formatting)
- Same code would be generated repeatedly
- Errors need explicit handling
Scripts save tokens and improve reliability vs generated code.
在以下情况添加实用脚本：
- 操作具有确定性（验证、格式化）
- 相同代码会被重复生成
- 需要显式处理错误
与生成的代码相比，脚本可以节省Token并提升可靠性。
When to Split Files
何时拆分文件
Split into separate files when:
- SKILL.md exceeds 100 lines
- Content has distinct domains (finance vs sales schemas)
- Advanced features are rarely needed
在以下情况拆分文件：
- SKILL.md内容超过100行
- 内容涉及不同的领域（如财务与销售架构）
- 高级功能很少被用到
Review Checklist
审核清单
After drafting, verify:
- Description includes triggers ("Use when...")
- SKILL.md under 100 lines
- No time-sensitive info
- Consistent terminology
- Concrete examples included
- References one level deep
起草完成后，验证以下内容：
- 描述包含触发条件（“适用于...”）
- SKILL.md内容不超过100行
- 无时效性信息
- 术语保持一致
- 包含具体示例
- 引用仅为一级深度