write-a-skill

Writing Skills

Process

Gather Requirements - Ask the user:

Gather requirements - ask user about:
- What task/domain does this skill cover?
  
  What task/domain does the skill cover?
- What specific use cases should it handle?
  
  What specific use cases should it handle?
- Does it need executable scripts or just instructions?
  
  Does it need executable scripts or just instructions?
- Is there any reference material to include?
  
  Any reference materials to include?

Draft the Skill - Create:

Draft the skill - create:
- SKILL.md with concise instructions
  
  SKILL.md with concise instructions
- If the content exceeds 500 lines, add additional reference files
  
  Additional reference files if content exceeds 500 lines
- If deterministic operations are needed, add utility scripts
  
  Utility scripts if deterministic operations needed
Review with the User - Show the draft and ask:

Review with user - present draft and ask:
- Does this cover your use cases?
  
  Does this cover your use cases?
- Is anything missing or unclear?
  
  Anything missing or unclear?
- Should any section be more detailed/concise?
  
  Should any section be more/less detailed?

Skill Structure

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

SKILL.md Template

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# 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](REFERENCE.md)]

Description Requirements

The description isthe only thing your agent sees when deciding which skill to load. It appears 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.

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 enough information to know:

Goal: Give your agent just enough info to know:

What capability the skill provides

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

When/why to trigger it (specific keywords, contexts, file types)

Format：

Format:

At most 1024 characters

Max 1024 chars
Write in the third person

Write in third person
First sentence: what it does

First sentence: what it does
Second sentence: "Use when [specific triggers]"

Second sentence: "Use when [specific triggers]"

Good Example：

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：

Bad example:

Helps with documents.

A bad example makes it impossible for your agent to distinguish it from other documentation skills.

The bad example gives your agent no way to distinguish this from other document skills.

When to Add Scripts

Add utility scripts in the following cases:

Add utility scripts when:

The operation is deterministic (validation, formatting)

Operation is deterministic (validation, formatting)
The same code would be generated repeatedly

Same code would be generated repeatedly
Errors need explicit handling

Errors need explicit handling

Scripts save more tokens than generated code and improve reliability.

Scripts save tokens and improve reliability vs generated code.

When to Split Files

Split into separate files in the following cases:

Split into separate files when:

SKILL.md exceeds 100 lines

SKILL.md exceeds 100 lines
The content has clear domain divisions (such as finance vs sales models)

Content has distinct domains (finance vs sales schemas)
Advanced features are rarely needed

Advanced features are rarely needed

Review Checklist

After drafting, please verify:

After drafting, verify:

The description includes trigger conditions ("Use when...")

Description includes triggers ("Use when...")
SKILL.md stays within 100 lines

SKILL.md under 100 lines
No time-sensitive information

No time-sensitive info
Consistent terminology

Consistent terminology
Includes concrete examples

Concrete examples included
References are one level deep

References one level deep