Back to Details

write-a-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write a Skill

编写技能

Create a new skill for the foundation-skills repository following all repo conventions.
遵循仓库的所有约定，为foundation-skills仓库创建新技能。

Workflow

工作流

Step 1: Gather requirements

步骤1：收集需求

Ask the user:
  • What task or domain does the skill cover?
  • What specific use cases should it handle?
  • What triggers should activate it? (keywords, phrases, file types)
  • Any reference materials to include?
向用户询问以下信息：
  • 该技能覆盖的任务或领域是什么？
  • 它需要处理哪些具体用例？
  • 应该由什么触发器激活它？（关键词、短语、文件类型）
  • 需要包含哪些参考材料？

Step 2: Choose a skill name

步骤2：选择技能名称

  • Use lowercase kebab-case (e.g., 
    my-new-skill
    )
  • Keep it short and descriptive
  • Verify the name is not already taken in 
    skills/
  • 使用小写短横线命名法（kebab-case，例如：
    my-new-skill
    ）
  • 保持简短且具有描述性
  • 确认该名称未被
    skills/
    目录下的现有技能占用

Step 3: Create 
skills/<name>/SKILL.md

步骤3：创建
skills/<name>/SKILL.md

Start from 
skills/_TEMPLATE/SKILL.md
but apply these mandatory conventions:
Frontmatter (YAML):
yaml
---
name: <skill-name>
description: <what it does>. Use when <triggers>.
version: 1.0.0
---
  • name
    , 
    description
    , 
    version
    are required and at root level (not nested under 
    metadata
    )
  • description
    max 1024 characters. First sentence: what it does. Second sentence: "Use when [triggers]."
  • version
    starts at 
    1.0.0
    for new skills
  • SKILL.md is written in English
Body rules:
  • Keep SKILL.md under 100 lines — concise, actionable instructions only
  • Use progressive disclosure: put detailed content in 
    reference/
    files
  • Include concrete examples
  • No time-sensitive information
从
skills/_TEMPLATE/SKILL.md
模板开始创建，但必须遵守以下强制约定：
Frontmatter（YAML格式）：
yaml
---
name: <skill-name>
description: <what it does>. Use when <triggers>.
version: 1.0.0
---
  • name
    、
    description
    、
    version
    为必填字段，且必须放在根层级（不要嵌套在
    metadata
    下）
  • description
    最长不超过1024个字符。第一句说明技能的作用，第二句格式为："Use when [triggers]."
  • 新技能的
    version
    从
    1.0.0
    开始
  • SKILL.md必须使用英文编写
正文规则：
  • SKILL.md的内容控制在100行以内——仅保留简洁、可执行的指引
  • 采用渐进式披露：将详细内容放在
    reference/
    目录下的文件中
  • 包含具体示例
  • 不要包含时效性信息

Step 4: Create reference files (if needed)

步骤4：创建参考文件（如有需要）

If content exceeds 100 lines or has distinct domains, split into:
skills/<name>/
├── SKILL.md
└── reference/
    ├── detailed-guide.md
    └── examples.md
Reference from SKILL.md: 
See [detailed guide](reference/detailed-guide.md)
如果内容超过100行或涉及不同领域，请拆分到以下目录结构：
skills/<name>/
├── SKILL.md
└── reference/
    ├── detailed-guide.md
    └── examples.md
在SKILL.md中引用方式：
See [detailed guide](reference/detailed-guide.md)

Step 5: Create 
docs/<name>.md

步骤5：创建
docs/<name>.md

Create the matching documentation file in French. It must include:
  • Title (skill name)
  • Description section
  • Cas d'usage (use cases)
  • Declenchement (triggers)
  • Fonctionnement (how it works)
  • Exemples (examples in both English and French)
  • Version number
See existing files in 
docs/
for style reference.
创建对应的法语文档文件，必须包含以下内容：
  • 标题（技能名称）
  • 描述部分
  • Cas d'usage（用例）
  • Declenchement（触发条件）
  • Fonctionnement（运行逻辑）
  • Exemples（示例，需同时提供英文和法文版本）
  • 版本号
可参考
docs/
目录下的现有文件确定样式规范。

Step 6: Review checklist

步骤6：审核检查清单

  • skills/<name>/SKILL.md
    exists with valid frontmatter (
    name
    , 
    description
    , 
    version
    at root)
  • Description includes triggers ("Use when...")
  • Description under 1024 characters
  • SKILL.md under 100 lines
  • SKILL.md written in English
  • docs/<name>.md
    exists, written in French
  • No time-sensitive info, consistent terminology
  • Concrete examples included
  • Reference files only one level deep
  • 已创建
    skills/<name>/SKILL.md
    ，且包含有效的frontmatter（根层级存在
    name
    、
    description
    、
    version
    字段）
  • 描述中包含触发条件（"Use when..."部分）
  • 描述长度不超过1024个字符
  • SKILL.md内容不超过100行
  • SKILL.md使用英文编写
  • 已创建
    docs/<name>.md
    ，且使用法语编写
  • 无时效性信息，术语使用统一
  • 包含具体示例
  • 参考文件仅嵌套一层目录

Versioning rules

版本控制规则

When modifying an existing skill, bump its 
version
field:
  • patch (1.0.0 -> 1.0.1): typo fixes, wording improvements, minor clarifications
  • minor (1.0.0 -> 1.1.0): new features, new sections, meaningful behavior changes
  • major (1.0.0 -> 2.0.0): breaking changes (renamed skill, removed features, restructured workflow)
修改现有技能时，需升级
version
字段：
  • 修订号（1.0.0 -> 1.0.1）：修复拼写错误、优化措辞、微小的内容澄清
  • 次版本号（1.0.0 -> 1.1.0）：新增功能、新增章节、明显的行为变更
  • 主版本号（1.0.0 -> 2.0.0）：破坏性变更（重命名技能、移除功能、重构工作流）

Important Notes

重要注意事项

  • Every skill lives in 
    skills/<name>/SKILL.md
    ; documentation in 
    docs/<name>.md
    (in French)
  • The 
    description
    field is the only thing the agent sees when choosing which skill to load — make it count
  • Scripts are discouraged; prefer Markdown instructions. Add scripts only for deterministic operations
  • 所有技能都存放在
    skills/<name>/SKILL.md
    路径下；文档存放在
    docs/<name>.md
    路径下（法语编写）
  • Agent选择加载哪个技能时仅会读取
    description
    字段    ——请确保该字段的信息准确有效
  • 不建议使用脚本；优先使用Markdown指引，仅用于确定性操作时可添加脚本