Back to Details

create-agent-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<essential_principles>
<essential_principles>

How Skills Work

技能工作原理

Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.
技能是基于文件系统的模块化能力，可按需提供领域专业知识。本技能将教授如何创建高效的技能。

1. Skills Are Prompts

1. 技能即提示词

All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.
所有提示词最佳实践均适用。表述清晰、直接，使用XML结构。默认Claude具备智能——仅添加Claude不具备的上下文信息。

2. SKILL.md Is Always Loaded

2. SKILL.md始终会被加载

When a skill is invoked, Claude reads SKILL.md. Use this guarantee:
  • Essential principles go in SKILL.md (can't be skipped)
  • Workflow-specific content goes in workflows/
  • Reusable knowledge goes in references/
当技能被调用时，Claude会读取SKILL.md。请利用这一特性：
  • 核心原则放在SKILL.md中（不可跳过）
  • 特定工作流内容放在workflows/目录下
  • 可复用知识放在references/目录下

3. Router Pattern for Complex Skills

3. 复杂技能的路由模式

skill-name/
├── SKILL.md              # Router + principles
├── workflows/            # Step-by-step procedures (FOLLOW)
├── references/           # Domain knowledge (READ)
├── templates/            # Output structures (COPY + FILL)
└── scripts/              # Reusable code (EXECUTE)
SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.
When to use each folder:
  • workflows/ - Multi-step procedures Claude follows
  • references/ - Domain knowledge Claude reads for context
  • templates/ - Consistent output structures Claude copies and fills (plans, specs, configs)
  • scripts/ - Executable code Claude runs as-is (deploy, setup, API calls)
skill-name/
├── SKILL.md              # 路由 + 原则
├── workflows/            # 分步流程（遵循执行）
├── references/           # 领域知识（阅读参考）
├── templates/            # 输出结构（复制填充）
└── scripts/              # 可复用代码（执行运行）
SKILL.md会询问“你想要做什么？”→ 路由到对应工作流 → 工作流指定需要读取哪些参考资料。
各目录适用场景：
  • workflows/ - Claude需遵循的多步骤流程
  • references/ - Claude用于获取上下文的领域知识
  • templates/ - Claude可复制并填充的标准化输出结构（计划、规格、配置文件等）
  • scripts/ - Claude可直接运行的可执行代码（部署、设置、API调用等）

4. Pure XML Structure

4. 纯XML结构

No markdown headings (#, ##, ###) in skill body. Use semantic XML tags:
xml
<objective>...</objective>
<process>...</process>
<success_criteria>...</success_criteria>
Keep markdown formatting within content (bold, lists, code blocks).
技能主体中不得使用Markdown标题（#、##、###）。请使用语义化XML标签：
xml
<objective>...</objective>
<process>...</process>
<success_criteria>...</success_criteria>
可在内容内部保留Markdown格式（粗体、列表、代码块）。

5. Progressive Disclosure

5. 渐进式披露

SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow. </essential_principles>
<intake> What would you like to do?
  1. Create new skill
  2. Audit/modify existing skill
  3. Add component (workflow/reference/template/script)
  4. Get guidance
Wait for response before proceeding. </intake>
<routing> | Response | Next Action | Workflow | |----------|-------------|----------| | 1, "create", "new", "build" | Ask: "Task-execution skill or domain expertise skill?" | Route to appropriate create workflow | | 2, "audit", "modify", "existing" | Ask: "Path to skill?" | Route to appropriate workflow | | 3, "add", "component" | Ask: "Add what? (workflow/reference/template/script)" | workflows/add-{type}.md | | 4, "guidance", "help" | General guidance | workflows/get-guidance.md |
Progressive disclosure for option 1 (create):
  • If user selects "Task-execution skill" → workflows/create-new-skill.md
  • If user selects "Domain expertise skill" → workflows/create-domain-expertise-skill.md
Progressive disclosure for option 3 (add component):
  • If user specifies workflow → workflows/add-workflow.md
  • If user specifies reference → workflows/add-reference.md
  • If user specifies template → workflows/add-template.md
  • If user specifies script → workflows/add-script.md
Intent-based routing (if user provides clear intent without selecting menu):
  • "audit this skill", "check skill", "review" → workflows/audit-skill.md
  • "verify content", "check if current" → workflows/verify-skill.md
  • "create domain expertise", "exhaustive knowledge base" → workflows/create-domain-expertise-skill.md
  • "create skill for X", "build new skill" → workflows/create-new-skill.md
  • "add workflow", "add reference", etc. → workflows/add-{type}.md
  • "upgrade to router" → workflows/upgrade-to-router.md
After reading the workflow, follow it exactly. </routing>
<quick_reference>
SKILL.md文件长度控制在500行以内。将详细内容拆分到参考文件中，仅加载当前工作流所需的内容。 </essential_principles>
<intake> 你想要做什么？
  1. 创建新技能
  2. 审核/修改现有技能
  3. 添加组件（工作流/参考资料/模板/脚本）
  4. 获取指导
请等待用户回复后再继续。 </intake>
<routing> | 回复内容 | 后续操作 | 工作流 | |----------|-------------|----------| | 1, "create", "new", "build" | 询问：“是任务执行类技能还是领域专业知识类技能？” | 路由到对应的创建工作流 | | 2, "audit", "modify", "existing" | 询问：“技能的路径是什么？” | 路由到对应的工作流 | | 3, "add", "component" | 询问：“要添加什么类型的组件？（workflow/reference/template/script）” | workflows/add-{type}.md | | 4, "guidance", "help" | 提供通用指导 | workflows/get-guidance.md |
选项1（创建）的渐进式披露：
  • 如果用户选择“任务执行类技能” → workflows/create-new-skill.md
  • 如果用户选择“领域专业知识类技能” → workflows/create-domain-expertise-skill.md
选项3（添加组件）的渐进式披露：
  • 如果用户指定workflow → workflows/add-workflow.md
  • 如果用户指定reference → workflows/add-reference.md
  • 如果用户指定template → workflows/add-template.md
  • 如果用户指定script → workflows/add-script.md
基于意图的路由（若用户未选择菜单但提供了明确意图）：
  • "audit this skill", "check skill", "review" → workflows/audit-skill.md
  • "verify content", "check if current" → workflows/verify-skill.md
  • "create domain expertise", "exhaustive knowledge base" → workflows/create-domain-expertise-skill.md
  • "create skill for X", "build new skill" → workflows/create-new-skill.md
  • "add workflow", "add reference"等 → workflows/add-{type}.md
  • "upgrade to router" → workflows/upgrade-to-router.md
阅读工作流后，请严格按照其步骤执行。 </routing>
<quick_reference>

Skill Structure Quick Reference

技能结构速查

Simple skill (single file):
yaml
---
name: skill-name
description: What it does and when to use it.
---

<objective>What this skill does</objective>
<quick_start>Immediate actionable guidance</quick_start>
<process>Step-by-step procedure</process>
<success_criteria>How to know it worked</success_criteria>
Complex skill (router pattern):
SKILL.md:
  <essential_principles> - Always applies
  <intake> - Question to ask
  <routing> - Maps answers to workflows

workflows/:
  <required_reading> - Which refs to load
  <process> - Steps
  <success_criteria> - Done when...

references/:
  Domain knowledge, patterns, examples

templates/:
  Output structures Claude copies and fills
  (plans, specs, configs, documents)

scripts/:
  Executable code Claude runs as-is
  (deploy, setup, API calls, data processing)
</quick_reference>
<reference_index>
简单技能（单文件）：
yaml
---
name: skill-name
description: What it does and when to use it.
---

<objective>What this skill does</objective>
<quick_start>Immediate actionable guidance</quick_start>
<process>Step-by-step procedure</process>
<success_criteria>How to know it worked</success_criteria>
复杂技能（路由模式）：
SKILL.md:
  <essential_principles> - 始终适用
  <intake> - 要询问的问题
  <routing> - 将答案映射到对应工作流

workflows/:
  <required_reading> - 需要加载的参考资料
  <process> - 步骤流程
  <success_criteria> - 完成标准

references/:
  领域知识、模式、示例

templates/:
  Claude可复制并填充的输出结构
  (计划、规格、配置文件、文档)

scripts/:
  Claude可直接运行的可执行代码
  (部署、设置、API调用、数据处理)
</quick_reference>
<reference_index>

Domain Knowledge

领域知识

All in 
references/
:
Structure: recommended-structure.md, skill-structure.md Principles: core-principles.md, be-clear-and-direct.md, use-xml-tags.md Patterns: common-patterns.md, workflows-and-validation.md Assets: using-templates.md, using-scripts.md Advanced: executable-code.md, api-security.md, iteration-and-testing.md </reference_index>
<workflows_index>
全部位于
references/
目录下：
结构类： recommended-structure.md, skill-structure.md 原则类： core-principles.md, be-clear-and-direct.md, use-xml-tags.md 模式类： common-patterns.md, workflows-and-validation.md 资产类： using-templates.md, using-scripts.md 进阶类： executable-code.md, api-security.md, iteration-and-testing.md </reference_index>
<workflows_index>

Workflows

工作流

All in 
workflows/
:
WorkflowPurpose
create-new-skill.mdBuild a skill from scratch
create-domain-expertise-skill.mdBuild exhaustive domain knowledge base for build/
audit-skill.mdAnalyze skill against best practices
verify-skill.mdCheck if content is still accurate
add-workflow.mdAdd a workflow to existing skill
add-reference.mdAdd a reference to existing skill
add-template.mdAdd a template to existing skill
add-script.mdAdd a script to existing skill
upgrade-to-router.mdConvert simple skill to router pattern
get-guidance.mdHelp decide what kind of skill to build
</workflows_index>
<yaml_requirements>
全部位于
workflows/
目录下：
工作流用途
create-new-skill.md从零开始构建技能
create-domain-expertise-skill.md为build/构建详尽的领域知识库
audit-skill.md根据最佳实践分析技能
verify-skill.md检查内容是否仍准确
add-workflow.md为现有技能添加工作流
add-reference.md为现有技能添加参考资料
add-template.md为现有技能添加模板
add-script.md为现有技能添加脚本
upgrade-to-router.md将简单技能转换为路由模式
get-guidance.md帮助确定要构建的技能类型
</workflows_index>
<yaml_requirements>

YAML Frontmatter

YAML前置元数据

Required fields:
yaml
---
name: skill-name          # lowercase-with-hyphens, matches directory
description: ...          # What it does AND when to use it (third person)
---
Name conventions: 
create-*
, 
manage-*
, 
setup-*
, 
generate-*
, 
build-*
</yaml_requirements>
<success_criteria> A well-structured skill:
  • Has valid YAML frontmatter
  • Uses pure XML structure (no markdown headings in body)
  • Has essential principles inline in SKILL.md
  • Routes directly to appropriate workflows based on user intent
  • Keeps SKILL.md under 500 lines
  • Asks minimal clarifying questions only when truly needed
  • Has been tested with real usage </success_criteria>
必填字段：
yaml
---
name: skill-name          # 小写连字符格式，与目录名匹配
description: ...          # 技能功能及适用场景（第三人称表述）
---
命名规范：
create-*
, 
manage-*
, 
setup-*
, 
generate-*
, 
build-*
</yaml_requirements>
<success_criteria> 结构良好的技能需满足：
  • 具备有效的YAML前置元数据
  • 使用纯XML结构（主体中无Markdown标题）
  • SKILL.md中内嵌核心原则
  • 根据用户意图直接路由到对应工作流
  • SKILL.md文件长度不超过500行
  • 仅在真正必要时提出最少的澄清问题
  • 已通过实际使用测试 </success_criteria>