skill-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Development

Skill开发

Guide for creating effective skills and contributing them to the communal knowledge base.

本指南介绍如何创建有效的Skill并将其贡献到公共知识库。

When to Use This Skill

何时使用本Skill

Creating skills:

Building a new skill for a specific domain or workflow
Updating an existing skill with improvements
Packaging skills for distribution

Contributing skills:

You discovered something that took significant time to figure out
Existing skill instructions were incomplete or led you astray
You repeatedly solve the same undocumented problem

创建Skill：

为特定领域或工作流构建新Skill
对现有Skill进行优化更新
打包Skill以便分发

贡献Skill：

你发现了某个需要花费大量时间才能解决的问题
现有Skill的说明不完整或存在误导性
你反复遇到同一个无文档记录的问题并解决它

Part 1: Creating Skills

第一部分：创建Skill

Skill Structure

Skill结构

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Files used in output

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Files used in output

SKILL.md Requirements

SKILL.md 要求

yaml

---
name: skill-name
description: What this skill does. Use when [triggers]. 
---

yaml

---
name: skill-name
description: What this skill does. Use when [triggers]. 
---

Skill Name

[Instructions in imperative form...]


**Metadata rules:**
- `name`: lowercase, hyphens, gerund form (e.g., `creating-skills`)
- `description`: Lead with action verbs, end with "Use when [triggers]"

[Instructions in imperative form...]


**元数据规则：**
- `name`: 小写、连字符连接、动名词形式（例如 `creating-skills`）
- `description`: 以动作动词开头，结尾为"Use when [触发场景]"

Writing Style

写作风格

Write in imperative/infinitive form (verb-first), not second person:

✅ "To accomplish X, do Y"
❌ "You should do X"

使用祈使/不定式形式（动词开头），而非第二人称：

✅ "要完成X，请执行Y"
❌ "你应该做X"

Progressive Disclosure

渐进式信息披露

Keep SKILL.md lean (<5k words). Move detailed content to

references/

Metadata (~100 words) - Always in context
SKILL.md body (<5k words) - When skill triggers
References (unlimited) - Loaded as needed by agent

保持SKILL.md简洁（少于5000字）。将详细内容移至

references/

元数据（约100字）- 始终置于上下文之中
SKILL.md 正文（少于5000字）- Skill触发时展示
参考资料（无字数限制）- 由Agent按需加载

Scripts

脚本

Include scripts for tasks that:

Are repeatedly rewritten
Require deterministic reliability
Save significant tokens

为以下类型的任务添加脚本：

需反复编写的任务
需要确定性可靠性的任务
可大幅节省Token的任务

Part 2: Contributing Skills

第二部分：贡献Skill

Core Philosophy

核心理念

This repository is a living knowledge base. Skills must contain general-purpose knowledge that helps many agents - not project-specific configs or personal preferences.

本知识库是一个动态更新的知识库。Skill必须包含通用知识，能够帮助众多Agent，而非仅适用于特定项目的配置或个人偏好。

What to Contribute

贡献内容指南

✅ Contribute	❌ Don't Contribute
Patterns that appear 3+ times	One-off solutions
General API/tool patterns	Project-specific configs
Battle-tested workarounds	Personal preferences
Gap in existing skills	Already documented elsewhere

✅ 建议贡献	❌ 请勿贡献
出现3次及以上的模式	一次性解决方案
通用API/工具模式	特定项目的配置
经实战验证的变通方案	个人偏好
现有Skill的内容空白	已在其他地方有文档记录的内容

Validation Checklist

验证清单

Before contributing, verify:

Is this generalizable beyond your specific context?
Have you seen this pattern multiple times?
Does this address a real gap vs. personal preference?
Would this help an agent on a completely different project?

贡献前请验证：

该内容是否可推广到你的特定场景之外？
你是否多次遇到该模式？
该内容是否填补了真实的空白，而非出于个人偏好？
该内容是否对完全不同项目中的Agent有帮助？

Contribution Process

贡献流程

Recognize - Notice patterns during work (time investment, repetition, corrections)
Validate - Confirm pattern is general, not specific to your context
Create branch -
```
add/skill-name
```
or
```
fix/skill-name
```
Submit PR - Clear description with rationale and evidence

See

references/pr-workflow.md

for detailed PR process.

识别 - 在工作中留意模式（如耗时投入、重复操作、修正内容）
验证 - 确认该模式具有通用性，而非仅适用于你的特定场景
创建分支 - 命名为
```
add/skill-name
```
或
```
fix/skill-name
```
提交PR - 提供清晰的描述、理由和相关依据

详见

references/pr-workflow.md

中的PR流程细节。

Scripts

脚本

```
scripts/init_skill.py
```
- Initialize skill directory structure
```
scripts/package_skill.py
```
- Package skill for distribution
```
scripts/quick_validate.py
```
- Validate SKILL.md format

```
scripts/init_skill.py
```
- 初始化Skill目录结构
```
scripts/package_skill.py
```
- 打包Skill以便分发
```
scripts/quick_validate.py
```
- 验证SKILL.md格式

References

参考资料

```
references/recognizing-learnings.md
```
- Patterns for spotting valuable learnings
```
references/validation-criteria.md
```
- Detailed validation guidelines
```
references/pr-workflow.md
```
- PR process and templates
```
references/contribution-examples.md
```
- Real contribution examples

references/progressive-disclosure-research.md

- Research on skill organization

```
references/recognizing-learnings.md
```
- 识别有价值经验的模式
```
references/validation-criteria.md
```
- 详细的验证准则
```
references/pr-workflow.md
```
- PR流程及模板
```
references/contribution-examples.md
```
- 真实贡献示例

references/progressive-disclosure-research.md

- Skill组织方式相关研究