create-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skill Creation

Agent Skill创建

Agent Skills are capability modules that give AI agents new abilities. Unlike workflows (which guide how to approach tasks), skills define what an agent can do. Skills are portable across 25+ agent products including Claude Code, Cursor, and VS Code.

Agent Skills 是为AI agent赋予新能力的功能模块。与指导如何完成任务的工作流不同，技能定义了agent可以做什么。技能可在25+款agent产品中移植使用，包括Claude Code、Cursor、VS Code。

When to Use

适用场景

Use this skill when you need to:

Create a new reusable AI agent capability
Scaffold a skill directory structure
Convert an existing guide or workflow into the Agent Skills format
Build a capability module for AI agents

当你需要完成以下操作时可使用该技能：

创建新的可复用AI agent能力
搭建技能目录结构
将现有指南或工作流转换为Agent Skills格式
为AI agent构建功能模块

About Skills

技能介绍

Skills are modular, self-contained packages that extend AI capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks - they transform a general-purpose agent into a specialized one equipped with procedural knowledge that no model can fully possess.

What Skills Provide:

Specialized workflows - Multi-step procedures for specific domains
Tool integrations - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, schemas, business logic
Bundled resources - Scripts, references, and assets for complex and repetitive tasks

技能是模块化、自包含的程序包，通过提供专业知识、工作流和工具来扩展AI能力。你可以把它们看作特定领域或任务的「入门指南」——它们能把通用agent转变为具备专业流程知识的专用agent，这类知识是任何大模型都无法完全自带的。

技能提供的内容：

专业工作流 - 特定领域的多步骤操作流程
工具集成 - 对接特定文件格式或API的操作说明
领域专业知识 - 企业专属知识、数据结构、业务逻辑
绑定资源 - 用于复杂重复任务的脚本、参考资料、资产

Process

操作流程

Step 1: Define the Skill

步骤1：定义技能

Before creating the skill, understand it through concrete examples. Ask questions like:

"What functionality should this skill support?"
"Can you give examples of how this skill would be used?"
"What would a user say that should trigger this skill?"

Then clarify its purpose:

What capability does this skill provide?
- Example: "Process PDF files", "Generate API documentation", "Manage database migrations"
When should it activate? (Critical for the description field)
- What user requests should trigger this skill?
- What keywords or contexts indicate this skill is needed?
- The description is the primary triggering mechanism - include all "when to use" information there, not in the body (the body is only loaded after triggering)
What resources does it need?
- Scripts for deterministic operations that are repeatedly rewritten?
- Reference documentation for domain knowledge?
- Templates or assets for output generation?
What's the scope?
- Keep skills focused on one capability
- Split large skills into multiple smaller ones

创建技能前，先通过具体案例理解技能定位，可自问以下问题：

「这个技能应该支持什么功能？」
「你能举几个这个技能的使用示例吗？」
「用户说出什么内容时应该触发这个技能？」

然后明确其定位：

该技能提供什么能力？
- 示例：「处理PDF文件」、「生成API文档」、「管理数据库迁移」
什么时候应该触发？（对描述字段至关重要）
- 什么用户请求应该触发该技能？
- 什么关键词或上下文表明需要使用该技能？
- 描述是主要触发机制——请将所有「适用场景」信息放在这里，不要放在正文里（正文仅在触发后才会加载）
需要什么资源？
- 用于反复执行的确定性操作的脚本？
- 用于领域知识的参考文档？
- 用于生成输出的模板或资产？
范围是什么？
- 保持技能聚焦于单一能力
- 大型技能可拆分为多个更小的技能

Step 2: Scaffold the Skill

步骤2：搭建技能脚手架

Run the Samuel CLI command:

bash

samuel skill create <skill-name>

Name Requirements:

Lowercase alphanumeric and hyphens only
No consecutive hyphens (
```
--
```
)
Cannot start or end with hyphen
Maximum 64 characters

This creates:

.claude/skills/<skill-name>/
├── SKILL.md           # Pre-filled template
├── scripts/           # For executable code
├── references/        # For additional docs
└── assets/            # For templates, data

运行Samuel CLI命令：

bash

samuel skill create <skill-name>

命名要求：

仅支持小写字母、数字和连字符
不允许连续连字符（
```
--
```
）
不能以连字符开头或结尾
最长64个字符

该命令会生成如下结构：

.claude/skills/<skill-name>/
├── SKILL.md           # 预填充的模板
├── scripts/           # 存放可执行代码
├── references/        # 存放额外文档
└── assets/            # 存放模板、数据

Step 3: Write SKILL.md

步骤3：编写SKILL.md

Edit the generated SKILL.md with:

编辑生成的SKILL.md，包含以下内容：

Required Frontmatter

必填前置元数据

yaml

---
name: skill-name
description: |
  What this skill does and when to use it.
  Include specific triggers and keywords.
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

Description Best Practices:

Describe both what and when
Include keywords that trigger activation
Be specific, not vague ("Process PDF files" not "Helps with documents")
Maximum 1024 characters

yaml

---
name: skill-name
description: |
  该技能的功能以及适用场景。
  包含具体触发条件和关键词。
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

描述编写最佳实践：

同时说明「功能是什么」和「什么时候用」
包含触发激活的关键词
具体明确，不要模糊（写「处理PDF文件」不要写「处理文档相关内容」）
最长1024个字符

Body Content

正文内容

Write clear instructions that tell the AI agent how to use this skill:

Purpose: What capability this provides
When to Use: Scenarios that trigger this skill
Instructions: Step-by-step procedure
Examples: Input/output pairs
Notes: Warnings, edge cases, best practices

Keep under 500 lines - use reference files for detailed content.

编写清晰的说明，告诉AI agent如何使用该技能：

用途：该技能提供什么能力
适用场景：触发该技能的场景
操作说明：分步操作流程
示例：输入/输出对
注意事项：警告、边界情况、最佳实践

保持正文在500行以内——详细内容请使用参考文件存放。

Step 4: Add Resources (Optional)

步骤4：添加资源（可选）

Scripts (

scripts/

)

脚本（

scripts/

）

Add executable code for deterministic operations:

python

undefined

为确定性操作添加可执行代码：

python

undefined

scripts/process.py

def process_data(input_path): # Implementation pass


**Script Best Practices**:
- Make scripts self-contained
- Include helpful error messages
- Handle edge cases
- Document parameters

def process_data(input_path): # 实现逻辑 pass


**脚本编写最佳实践**：
- 保持脚本自包含
- 包含友好的错误提示
- 处理边界情况
- 为参数添加文档

References (

references/

)

参考资料（

references/

）

Add documentation that AI loads on-demand:

markdown

undefined

添加AI按需加载的文档：

markdown

undefined

references/api-guide.md

API Endpoints

API端点

...


Use references for:
- Detailed technical docs
- Domain-specific knowledge
- Large examples
- Configuration guides

...


参考资料适用于存放：
- 详细技术文档
- 领域专属知识
- 大型示例
- 配置指南

Assets (

assets/

)

资产（

assets/

）

Add templates and data files:

assets/
├── template.html
├── config.json
└── icons/

添加模板和数据文件：

assets/
├── template.html
├── config.json
└── icons/

Step 5: Validate

步骤5：校验

Run validation to check against Agent Skills spec:

bash

samuel skill validate <skill-name>

Validation Checks:

SKILL.md exists with valid YAML frontmatter
Name matches directory name
Name format is correct
Description is present
No fields exceed length limits

Fix any errors before proceeding.

运行校验命令检查是否符合Agent Skills规范：

bash

samuel skill validate <skill-name>

校验内容：

SKILL.md存在且包含合法的YAML前置元数据
名称与目录名匹配
名称格式正确
描述已填写
没有字段超过长度限制

继续下一步前请修复所有错误。

Step 6: Test

步骤6：测试

Test the skill with real tasks:

Load the skill in your AI agent
Try scenarios from "When to Use"
Verify instructions are followed correctly
Check that examples produce expected output
Test edge cases

用真实任务测试技能：

在你的AI agent中加载该技能
尝试「适用场景」中列出的场景
验证AI是否正确遵循操作说明
检查示例是否生成预期输出
测试边界情况

Step 7: Document

步骤7：归档文档

If the skill is significant, record in

.claude/memory/

markdown

undefined

如果是重要技能，在

.claude/memory/

中记录：

markdown

undefined

.claude/memory/YYYY-MM-DD-skill-name.md

Skill Created: <skill-name>

已创建技能：<skill-name>

Purpose: Brief description

Key Decisions:

Why this approach
Alternatives considered

Testing Notes:

What worked
What needed adjustment

---

用途：简要描述

关键决策：

为什么选择该方案
考虑过的替代方案

测试记录：

哪些部分运行正常
哪些部分需要调整

---

Best Practices

最佳实践

Concise is Key

简洁至上

The context window is a public good. Skills share it with everything else: system prompt, conversation history, other skills' metadata, and the actual user request. Default assumption: the AI is already very smart. Only add context it doesn't already have. Challenge each piece of information: "Does this paragraph justify its token cost?"

Good (50 tokens):

markdown

undefined

上下文窗口是公共资源，会被系统提示词、对话历史、其他技能的元数据、实际用户请求等所有内容共享。默认假设：AI已经非常聪明，仅添加它不具备的上下文。对每一条信息都要质疑：「这段内容消耗的token值得吗？」

正面示例（50 token）：

markdown

undefined

Extract PDF Text

提取PDF文本

Use pdfplumber:

python

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()


**Bad** (150 tokens):
```markdown

使用pdfplumber：

python

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()


**反面示例**（150 token）：
```markdown

Extract PDF Text

提取PDF文本

PDF files are a common format... [unnecessary explanation]

undefined

PDF是一种常见的文件格式... [不必要的解释]

undefined

Set Appropriate Degrees of Freedom

设置合适的自由度

Match the level of specificity to the task's fragility and variability. Think of the AI as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

Freedom Level	When to Use	Implementation	Example
High	Multiple valid approaches	Text-based instructions	Code review process
Medium	Preferred pattern exists	Pseudocode or scripts with parameters	Report generation
Low	Fragile/critical operations	Specific scripts, few parameters	Database migrations

根据任务的脆弱性和可变性匹配说明的具体程度。你可以把AI看作探路者：两侧是悬崖的窄桥需要明确的护栏（低自由度），而开阔的旷野允许多种路径（高自由度）。

自由度等级	适用场景	实现方式	示例
高	存在多种有效方案	文本说明	代码评审流程
中	存在推荐模式	伪代码或带参数的脚本	报告生成
低	脆弱/关键操作	特定脚本、少量参数	数据库迁移

Use Progressive Disclosure

使用渐进式披露

Metadata (~100 tokens): Always loaded
SKILL.md body (<5000 tokens): Loaded on activation
References/Scripts: Loaded on-demand

Keep SKILL.md lean; move details to reference files.

元数据（~100 token）：始终加载
SKILL.md 正文（<5000 token）：触发时加载
参考资料/脚本：按需加载

保持SKILL.md精简，将详细内容移到参考文件中。

What NOT to Include

不要包含的内容

A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation like README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, or CHANGELOG.md. The skill should only contain information needed for an AI agent to do the job at hand.

技能仅应包含直接支撑其功能的必要文件，不要创建多余的文档，比如README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md。技能仅应包含AI agent完成当前任务所需的信息。

Bundled Resource Guidelines

绑定资源指南

Scripts (
```
scripts/
```
): Include when the same code is being rewritten repeatedly or deterministic reliability is needed. Scripts may be executed without loading into context, saving tokens.
References (
```
references/
```
): For documentation the AI should reference while working. Keeps SKILL.md lean; loaded only when determined needed. If files are large (>10k words), include grep search patterns in SKILL.md. Avoid duplication - information should live in either SKILL.md or references, not both.
Assets (
```
assets/
```
): Files not intended to be loaded into context, but used in the output (templates, images, boilerplate code, fonts).

脚本（
```
scripts/
```
）：当同一段代码被反复编写，或是需要确定性可靠性时添加。脚本可以不用加载到上下文就直接执行，节省token。
参考资料（
```
references/
```
）：存放AI工作时需要参考的文档，保持SKILL.md精简，仅在需要时加载。如果文件很大（>1万字），在SKILL.md中添加grep搜索模式。避免重复——信息要么放在SKILL.md要么放在参考资料中，不要两边都放。
资产（
```
assets/
```
）：不需要加载到上下文，而是用于输出的文件（模板、图片、样板代码、字体）。

Provide Examples

提供示例

Examples teach better than explanations:

markdown

undefined

示例比解释效果更好：

markdown

undefined

Example: User Request

示例：用户请求

Input: "Help me merge these PDFs"

Output:

python

undefined

输入：「帮我合并这些PDF」

输出：

python

undefined

Code that handles the request

处理请求的代码

undefined

undefined

Checklist

检查清单

Before finalizing your skill:

Name follows conventions (lowercase, hyphens, max 64 chars)
Description is specific and under 1024 chars
SKILL.md body is under 500 lines
Instructions are clear and step-by-step
Examples show input/output pairs
Validation passes (
```
samuel skill validate
```
)
Tested with real scenarios
Scripts handle errors gracefully (if applicable)

最终确定技能前请检查：

名称符合规范（小写、连字符分隔、最长64字符）
描述具体明确，长度在1024字符以内
SKILL.md正文在500行以内
操作说明清晰，分步展示
包含输入/输出对示例
校验通过（
```
samuel skill validate
```
）
已通过真实场景测试
脚本可优雅处理错误（如有）

create-skill

Original

Translation

Agent Skill Creation

Agent Skill创建

When to Use

适用场景

About Skills

技能介绍

Process

操作流程

Step 1: Define the Skill

步骤1：定义技能

Step 2: Scaffold the Skill

步骤2：搭建技能脚手架

Step 3: Write SKILL.md

步骤3：编写SKILL.md

Required Frontmatter

必填前置元数据

Body Content

正文内容

Step 4: Add Resources (Optional)

步骤4：添加资源（可选）

Scripts (scripts/)

脚本（scripts/）

scripts/process.py

scripts/process.py

References (references/)

参考资料（references/）

references/api-guide.md

references/api-guide.md

API Endpoints

API端点

Assets (assets/)

资产（assets/）

Step 5: Validate

步骤5：校验

Step 6: Test

步骤6：测试

Step 7: Document

步骤7：归档文档

.claude/memory/YYYY-MM-DD-skill-name.md

.claude/memory/YYYY-MM-DD-skill-name.md

Skill Created: <skill-name>

已创建技能：<skill-name>

Best Practices

最佳实践

Concise is Key

简洁至上

Extract PDF Text

提取PDF文本

Extract PDF Text

提取PDF文本

Set Appropriate Degrees of Freedom

设置合适的自由度

Use Progressive Disclosure

使用渐进式披露

What NOT to Include

不要包含的内容

Bundled Resource Guidelines

绑定资源指南

Provide Examples

提供示例

Example: User Request

示例：用户请求

Code that handles the request

处理请求的代码

Checklist

检查清单

Related

相关资源

Scripts (
`scripts/`
)

脚本（
`scripts/`
）

References (
`references/`
)

参考资料（
`references/`
）

Assets (
`assets/`
)

资产（
`assets/`
）