write-a-skill

Writing Skills

Process

1. Gather requirements - Ask the user:

   • What task/domain does the skill cover?
   • What specific use cases should it handle?
   • Does it need executable scripts or just instructions?
   • Is there any reference material to include?

2. Draft the skill - Create:

   • SKILL.md with concise instructions
   • Additional reference files if content exceeds 500 lines
   • Tool scripts if deterministic operations are needed

3. Review with the user - Present the draft and ask:

   • Does this cover your use cases?
   • Is anything missing or unclear?
   • Should any section be more or less detailed?

Skill structure

skill-name/
├── SKILL.md           # 主要指令（必需）
├── REFERENCE.md       # 详细文档（如果需要）
├── EXAMPLES.md        # 使用示例（如果需要）
└── scripts/           # 工具脚本（如果需要）
    └── helper.js

SKILL.md template

---
name: skill-name
description: 能力的简要描述。当[特定触发器]时使用。
---

# 技能名称

## 快速开始

[最小工作示例]

## 工作流程

[带有复杂任务清单的逐步流程]

## 高级功能

[链接到单独文件：参见 [REFERENCE.md](REFERENCE.md)]

Description requirements

The description isthe only thing your agent sees when deciding which skill to load. It is shown in the system prompt alongside all other installed skills. Your agent reads these descriptions and selects the relevant skill based on the user's request.

Goal: give your agent enough information to know:

1. What capability this skill provides
2. When/why to trigger it (specific keywords, context, file types)

Format：

• At most 1024 characters
• Write in third person
• First sentence: what it does
• Second sentence: "Use when [specific triggers]"

Good example：

从 PDF 文件中提取文本和表格，填写表单，合并文档。当处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。

Bad example：

帮助处理文档。

The bad example does not give your agent any way to distinguish this from other documentation skills.

When to add scripts

Add tool scripts when:

• The operation is deterministic (validation, formatting)
• The same code would be generated repeatedly
• Errors need explicit handling

Scripts save tokens and improve reliability compared to generated code.

When to split files

Split into separate files when:

• SKILL.md exceeds 100 lines
• Content has distinct domains (finance and sales patterns)
• Advanced features are rarely needed

Review checklist

After drafting, verify:

• Description includes triggers ("Use when...")
• SKILL.md is under 100 lines
• No time-sensitive information
• Consistent terminology
• Includes concrete examples
• References are one level deep