skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator

Skill 创建指南

Create effective agent skills using progressive disclosure. Skills are workflow capabilities, not documentation dumps. The goal is loading the right information at the right time.

使用渐进式信息披露方法创建高效的Agent技能。Skills是工作流能力，而非文档堆砌。核心目标是在正确的时机加载正确的信息。

Core Principle

核心原则

Skills ≠ Documentation

```
devops
```
isn't "Cloudflare docs" → it's the ability to deploy infrastructure
```
ui-styling
```
isn't "Tailwind docs" → it's the ability to design interfaces
Each skill teaches how to perform a task, not what a tool does

Skills ≠ 文档

```
devops
```
并非「Cloudflare 文档」→ 而是部署基础设施的能力
```
ui-styling
```
并非「Tailwind 文档」→ 而是设计界面的能力
每个Skill教授的是如何完成任务，而非工具是什么

3-Tier Architecture

三层架构

Tier 1: Metadata (always loaded)
├── YAML frontmatter only (~100 words)
└── Enough for Claude to decide relevance

Tier 2: SKILL.md entry point (loaded on activation)
├── ~200 lines MAX
├── Overview, quick start, navigation
└── Points to references (doesn't include them)

Tier 3: references/ (loaded on-demand)
├── 200-300 lines each
├── Detailed documentation
└── Focused on single topics

Tier 1: 元数据（始终加载）
├── 仅包含YAML前置内容（约100词）
└── 为Claude提供足够的相关性判断依据

Tier 2: SKILL.md 入口文件（激活时加载）
├── 最多约200行
├── 包含概述、快速开始、导航指引
└── 指向参考文档（不包含具体内容）

Tier 3: references/ 目录（按需加载）
├── 每个文件200-300行
├── 详细文档内容
└── 聚焦单一主题

The 200-Line Rule

200行规则

Entry point MUST be under 200 lines. This enables:

Fast relevance scanning
Quick reference selection
400-700 lines of relevant context vs 1,000+ of mixed relevance

If you can't fit core instructions in 200 lines, you're putting too much in the entry point.

入口文件必须控制在200行以内。这能实现：

快速扫描相关性
快速选择参考内容
加载400-700行相关上下文，而非1000+行混合内容

如果核心说明无法压缩到200行以内，说明你在入口文件中塞入了过多内容。

Skill Structure

Skill 结构

skills/my-skill/
├── SKILL.md              # Entry point (<200 lines)
├── references/           # Detailed content
│   ├── guide-a.md        # 200-300 lines each
│   ├── guide-b.md
│   └── examples.md
├── scripts/              # Optional executable code
└── assets/               # Optional templates

skills/my-skill/
├── SKILL.md              # 入口文件（<200行）
├── references/           # 详细内容目录
│   ├── guide-a.md        # 每个文件200-300行
│   ├── guide-b.md
│   └── examples.md
├── scripts/              # 可选可执行代码目录
└── assets/               # 可选模板目录

SKILL.md Template

SKILL.md 模板

markdown

---
name: skill-name
description: One-line description. When to use this skill.
tools: Read, Write, Edit, Bash  # Optional
model: opus                      # Optional
---

markdown

---
name: skill-name
description: 一行描述。说明何时使用该Skill。
tools: Read, Write, Edit, Bash  # 可选
model: opus                      # 可选
---

Skill Name

Skill 名称

Brief description (2-3 sentences max).

简短描述（最多2-3句话）。

Quick Start

快速开始

```bash

Essential commands only

仅保留必要命令

```

Workflow

工作流

1. First Step

1. 第一步

Key points only
No lengthy explanations

仅保留关键点
避免冗长解释

2. Second Step

2. 第二步

Action-oriented
Link to references for details

以行动为导向
链接到参考文档查看详情

References

参考文档

Reference	Purpose
`references/detailed-guide.md`	Full implementation details
`references/examples.md`	Code examples

undefined

参考文档	用途
`references/detailed-guide.md`	完整实现细节
`references/examples.md`	代码示例

undefined

Writing Guidelines

写作指南

Imperative tone: "Run the build" not "You should run the build"
Action-oriented: What to do, not what things are
Progressive detail: Overview → Reference → Implementation
No redundancy: Say it once, in the right place

命令式语气：使用「运行构建命令」而非「你应该运行构建命令」
行动导向：说明要做什么，而非事物是什么
渐进式细节：概述 → 参考文档 → 实现细节
无冗余：只说一次，放在正确的位置

When to Create vs Reference

创建Skill vs 参考文档的适用场景

Create a skill when:

Task requires specific workflow knowledge
Multiple steps with decision points
Reusable across projects

Use references when:

Detailed implementation specifics
Code examples
Edge cases and troubleshooting

创建Skill的场景：

任务需要特定的工作流知识
包含多步骤及决策点
可跨项目复用

使用参考文档的场景：

详细的实现细节
代码示例
边缘情况与故障排查

Refactoring Bloated Skills

重构臃肿Skills

Signs you need to refactor:

SKILL.md over 200 lines
Loading 5+ skills causes context issues
90% of loaded content isn't used

Process:

Extract detailed sections to
```
references/
```
Keep only overview in SKILL.md
Add navigation table to references
Test cold start (should load <500 lines)

需要重构的信号：

SKILL.md 超过200行
加载5个以上Skill时出现上下文问题
90%的加载内容从未被使用

重构流程：

将详细内容提取到
```
references/
```
目录
SKILL.md 仅保留概述内容
为参考文档添加导航表格
测试冷启动（加载内容应<500行）

References

参考文档

Reference	Purpose
`references/architecture.md`	3-tier system deep dive
`references/frontmatter.md`	YAML frontmatter spec
`references/writing-guide.md`	Content writing best practices
`references/refactoring.md`	How to split bloated skills
`references/anti-patterns.md`	What NOT to do
`references/examples.md`	Complete skill examples

参考文档	用途
`references/architecture.md`	三层系统深度解析
`references/frontmatter.md`	YAML前置内容规范
`references/writing-guide.md`	内容写作最佳实践
`references/refactoring.md`	臃肿Skill拆分方法
`references/anti-patterns.md`	禁忌做法
`references/examples.md`	完整Skill示例

Metrics

衡量指标

After creating/refactoring a skill:

Entry point: <200 lines ✓
Each reference: 200-300 lines ✓
Cold start load: <500 lines ✓
Relevant info ratio: >80% ✓

创建/重构Skill后需满足：

入口文件：<200行 ✓
每个参考文档：200-300行 ✓
冷启动加载：<500行 ✓
相关信息占比：>80% ✓