write-a-skill

Writing Skills

Process

1. Gather requirements — Ask the user:

   • What task/domain does this skill cover?
   • What specific use cases should it handle?
   • Are executable scripts needed, or are instructions sufficient?
   • What reference materials need to be included?

2. Draft the skill — Create:

   • A SKILL.md containing concise instructions
   • If the content exceeds 500 lines, add additional reference files
   • If deterministic operations are needed, add tool scripts

3. Review with the user — Show the draft and ask:

   • Does this cover your use cases?
   • Is anything missing or unclear?
   • Which parts need more/less detail?

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 choosing which skill to load. It appears in the system prompt alongside other installed skills. Your agent reads these descriptions and selects the relevant skill based on the user's request.

Goal: Give the agent just enough information to know:

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

Format：

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

Good example：

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

Bad example：

帮助处理文档。

The bad example makes it impossible for the agent to distinguish it from other document-related skills.

When to Add Scripts

Add tool scripts when:

• The operation is deterministic (validation, formatting)
• The same code gets generated repeatedly
• Error handling needs to be explicitly defined

Scripts save tokens and improve reliability compared to generated code.

When to Split Files

Split content into separate files when:

• SKILL.md exceeds 100 lines
• The content has clear domain divisions (e.g., finance vs sales models)
• Advanced features are rarely used

Review Checklist

After drafting, verify:

• The description includes trigger conditions ("Use when...")
• SKILL.md is within 100 lines
• No time-sensitive information
• Terminology is consistent
• Includes concrete examples
• References are no more than one level deep