skill-master

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Master

Create and improve skills through conversation. The key insight: skills capture workflows, and the best way to understand a workflow is to experience it together.

通过对话创建并优化技能。核心思路：技能是对工作流的固化，而理解工作流的最佳方式是共同实践。

Core Approach

核心方法

Don't jump to drafting. The most common mistake is writing a skill before fully understanding what it should do. Instead:

Engage with the task itself - When a user describes what they want, try solving it with them first. This reveals edge cases, preferences, and implicit requirements that wouldn't surface in an interview.
Notice patterns - As you work through the task, observe what context you need, what decisions require judgment, what steps are always the same, and what varies.
Probe one question at a time - When engagement leaves gaps, fill them through
```
AskUserQuestion
```
. Ask one question, propose a recommended answer with a one-line reason, wait for the response before asking the next. Each answer informs the next question. Never batch.
Draft when ready - Only write the skill once you understand the workflow well enough to explain it to another Claude instance.
Delegate heavy reading - If the user references long transcripts, multi-file codebases, or large attached docs, spawn
```
Explore
```
or
```
general-purpose
```
to read. Light material — the existing skill, a short doc, a single file — read directly.

**不要急于起草。**最常见的错误是在完全理解技能应实现的功能之前就开始撰写。正确的做法是：

深入参与任务本身 - 当用户描述需求时，先和他们一起解决具体问题。这能揭示出访谈中不会浮现的边缘情况、偏好和隐含需求。
识别模式 - 在处理任务的过程中，观察需要哪些上下文、哪些决策需要判断、哪些步骤固定不变、哪些步骤会变化。
逐个提问探究 - 当参与过程中存在信息缺口时，通过
```
AskUserQuestion
```
来填补。一次只提一个问题，附带推荐答案和一行理由，等待回复后再提出下一个问题。每个答案都为下一个问题提供依据，绝不批量提问。
准备就绪再起草 - 只有当你对工作流足够了解，能够向另一个Claude实例解释清楚时，再开始撰写技能文档。
委托繁重的阅读工作 - 如果用户提及冗长的记录、多文件代码库或大型附件文档，调用
```
Explore
```
或通用型Agent来阅读。对于轻量内容——现有技能文档、短文档、单个文件——直接阅读即可。

Creating a New Skill

创建新技能

When a user wants to create a skill:

If they describe a task: Offer to work through it together first. "Let's try this together - describe a specific example and I'll help you accomplish it. That'll help me understand exactly what the skill should do."

If they have a workflow in mind: Ask them to walk you through it with a real example. Watch for:

What information do they provide upfront vs. what do you need to ask for?
Where do they make judgment calls?
What output format do they expect?
What would make this fail?

If they're capturing a conversation: Extract from the conversation history what context was needed, what steps were taken, what corrections were made, and what the final output looked like.

当用户想要创建新技能时：

如果他们描述了一项任务： 提议先一起完成该任务。“我们一起来实践这个任务吧——描述一个具体示例，我会帮你完成它。这能让我准确理解技能应该实现什么功能。”

如果他们已有工作流构想： 请他们结合实际示例逐步讲解。留意以下要点：

他们预先提供了哪些信息，哪些需要你主动询问？
他们在哪些环节需要做出判断？
他们期望的输出格式是什么？
哪些情况会导致任务失败？

如果他们想要固化一段对话： 从对话历史中提取所需的上下文、执行的步骤、做出的修正以及最终输出的形态。

Decisions to resolve

需要明确的决策

Once engagement reveals enough of the workflow, walk these decisions in dependency order. Each gates the next — don't jump branches until the current one is resolved.

Triggers — what phrases, file types, or contexts activate this skill? Gates everything downstream because trigger phrasing defines scope.
Scope — what range of tasks does this procedure cover, and what falls outside? Bounds what the skill is responsible for encoding vs. what stays general.
Output — what does success look like? Format, shape, examples.
Degrees of freedom — text instructions, parameterized templates, or exact scripts. Match to task fragility.
Structure — single SKILL.md, references, or scripts. Falls out of the previous answers.

Walk one at a time via

AskUserQuestion

, recommendation-first.

当参与过程揭示了足够多的工作流细节后，按依赖顺序逐一明确以下决策。每个决策都是下一个决策的前提——在当前决策未明确前，不要跳至下一环节。

触发条件 —— 哪些短语、文件类型或上下文会激活该技能？这是所有后续工作的基础，因为触发措辞定义了技能的适用范围。
适用范围 —— 该流程能处理哪些任务，哪些任务不在其范围内？明确技能需要编码实现的内容，以及哪些内容保持通用即可。
输出标准 —— 成功的输出是什么样的？包括格式、结构和示例。
自由度等级 —— 是采用文本指令、参数化模板还是精确脚本？根据任务的稳定性选择合适的方式。
结构形式 —— 单个SKILL.md文件、带引用文档还是附带脚本？由前面的决策结果决定。

通过

AskUserQuestion

逐个推进，每次先给出推荐方案。

Probing tactics

探究策略

Layer these onto the decision walk so each answer is actually load-bearing. Deploy as the situation calls, not as a checklist.

Press for definitions - When the user says "smarter triggering", "more robust handling", "better description", or other fuzzy terms, force a concrete version — specific phrases, observable behavior. Propose a sharp definition they can accept with one tap.
Surface assumptions - Check the framing before walking the tree. Is this one skill or three? Is the workflow actually reusable, or one-off? Is the user reaching for a skill when a CLAUDE.md note would fit better?
Test consequences - After each answer, trace the implication. "If the trigger is X, this also fires on Y — OK?" / "If freedom is high, output will vary across runs — OK?"
Probe with counterexamples - Stress-test a tentative decision before locking it in. "Would this correctly not fire when user says Z?" If it breaks, revisit before moving down the branch.

将以下策略融入决策推进过程，确保每个答案都有实际价值。根据具体情况灵活运用，而非按清单执行。

明确定义 - 当用户提到“更智能的触发”“更稳健的处理”“更优的描述”等模糊表述时，要求给出具体版本——特定短语、可观察的行为。提出清晰的定义供用户一键确认。
揭示隐含假设 - 在推进决策树之前，先检查框架。这是一个技能还是三个？工作流是否真的可复用，还是一次性的？用户是否在需要CLAUDE.md笔记时错误地选择了创建技能？
测试后果 - 每个答案给出后，追踪其影响。“如果触发条件是X，那么当用户提到Y时也会触发——可以接受吗？” / “如果自由度很高，不同运行的输出会有所差异——可以接受吗？”
用反例探究 - 在锁定决策前，用反例进行压力测试。“当用户提到Z时，该技能是否能正确不触发？”如果出现问题，在进入下一环节前重新审视决策。

Improving an Existing Skill

优化现有技能

When a user wants to improve a skill:

Read the current skill - Understand what it claims to do and how it's structured.
Identify gaps - Either from user feedback ("it doesn't handle X well") or by analyzing against best practices:
- Is the description specific enough for triggering?
- Is the content concise or bloated?
- Are instructions clear or ambiguous?
- Does it handle common edge cases?
Probe the gaps - Same one-at-a-time, recommendation-first pattern as Core Approach #3, scoped to the gaps you identified rather than re-interviewing broadly.
Optionally, test the workflow - Have the user describe a task the skill should handle. Try it and see where it falls short.

当用户想要优化现有技能时：

阅读当前技能文档 - 理解其宣称的功能和结构。
识别缺口 - 要么来自用户反馈（“它不能很好地处理X”），要么通过对照最佳实践分析：
- 描述是否足够具体以确保触发准确？
- 内容是简洁还是冗余？
- 指令是清晰还是模糊？
- 是否处理了常见的边缘情况？
探究缺口 - 采用核心方法第3点中逐个提问、先给出推荐方案的模式，但聚焦于已识别的缺口，而非广泛重新调研。
可选：测试工作流 - 让用户描述一个该技能应处理的任务，尝试执行并找出不足。

Writing the Skill

撰写技能文档

Structure

结构

skill-name/
├── SKILL.md           # Main instructions (required, <500 lines)
├── references/        # Detailed docs loaded on-demand
└── scripts/           # Utility scripts (if needed)

File naming tips:

Use forward slashes for paths (
```
reference/guide.md
```
, not
```
reference\guide.md
```
)
Name files descriptively:
```
form_validation_rules.md
```
, not
```
doc2.md
```

Organize by domain:

reference/finance.md

reference/sales.md

(not

docs/file1.md

)

skill-name/
├── SKILL.md           # 主指令文档（必填，<500行）
├── references/        # 按需加载的详细文档
└── scripts/           # 实用脚本（如有需要）

文件命名技巧：

路径使用正斜杠（
```
reference/guide.md
```
，而非
```
reference\guide.md
```
）
文件命名要描述性：
```
form_validation_rules.md
```
，而非
```
doc2.md
```

按领域组织：

reference/finance.md

、

reference/sales.md

（而非

docs/file1.md

）

Progressive Disclosure Patterns

渐进式披露模式

Pattern 1: High-level guide with references

markdown

undefined

模式1：高级指南加引用

markdown

undefined

PDF Processing

Quick start

快速入门

[Minimal example here]

[此处为极简示例]

Advanced features

高级功能

Form filling: See FORMS.md for complete guide API reference: See REFERENCE.md for all methods


**Pattern 2: Domain-specific organization**
```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing)
    ├── sales.md (pipeline, accounts)
    └── product.md (usage, features)
```
Claude reads only the relevant domain file.

**Pattern 3: Conditional details**
```markdown

表单填充：完整指南请见FORMS.md API参考：所有方法请见REFERENCE.md


**模式2：按领域组织**
```
bigquery-skill/
├── SKILL.md（概述和导航）
└── reference/
    ├── finance.md（收入、账单）
    ├── sales.md（销售漏斗、客户账户）
    └── product.md（使用情况、功能）
```
Claude仅读取相关领域的文件。

**模式3：条件式细节**
```markdown

Creating documents

创建文档

Use docx-js for new documents. See DOCX-JS.md.

使用docx-js创建新文档。请见DOCX-JS.md。

Editing documents

编辑文档

For simple edits, modify XML directly. For tracked changes: See REDLINING.md


**Tip:** For reference files >100 lines, include a table of contents at the top so Claude can see available sections even when previewing with partial reads.

对于简单编辑，直接修改XML即可。 如需跟踪修改：请见REDLINING.md


**提示：** 对于超过100行的参考文件，在顶部添加目录，这样即使Claude仅部分预览，也能看到可用的章节。

SKILL.md Template

SKILL.md模板

markdown

---
name: skill-name
description: >
  Brief description of capability. Use when [specific triggers].
  Include keywords users might say.
---

markdown

---
name: skill-name
description: >
  功能简要描述。适用于[特定触发场景]。
  包含用户可能使用的关键词。
---

Skill Name

Quick Start

快速入门

[Minimal working example or first steps]

[最简工作示例或第一步操作]

Workflow

工作流

[Step-by-step process, with decision points if needed]

[分步流程，如有需要可包含决策点]

Advanced

高级功能

[Link to reference files if content exceeds main file] See references/advanced.md for details.

undefined

[如果内容超出主文件，链接到参考文件] 详情请见references/advanced.md。

undefined

Description Guidelines

描述指南

The description is the only thing Claude sees when deciding whether to load a skill. It must include:

What the skill does (first sentence)
When to trigger it (second sentence, "Use when...")
Key trigger words/contexts

Good: "Generate BigQuery queries for sales analytics. Use when user asks about sales data, revenue metrics, pipeline analysis, or mentions BigQuery and sales in the same request."

Bad: "Helps with data queries."

描述是Claude决定是否加载技能时唯一会查看的内容。必须包含：

技能的功能（第一句）
触发时机（第二句，“适用于……”）
关键触发词/上下文

良好示例： "为销售分析生成BigQuery查询语句。适用于用户询问销售数据、收入指标、销售漏斗分析，或在同一请求中同时提及BigQuery和销售的场景。"

不良示例： "帮助处理数据查询。"

Naming Conventions

命名规范

Use consistent naming with lowercase letters, numbers, and hyphens only. Prefer gerund form (verb + -ing) for clarity:

Good:

processing-pdfs

analyzing-spreadsheets

managing-databases

Avoid:
```
helper
```
,
```
utils
```
,
```
tools
```
(too vague)

使用一致的命名方式，仅包含小写字母、数字和连字符。优先使用动名词形式（动词+-ing）以确保清晰：

Writing Principles

撰写原则

Concise is key. Claude is already smart - only add context it doesn't have. Challenge each piece:

"Does Claude really need this explanation?"
"Can I assume Claude knows this?"
"Does this paragraph justify its token cost?"

Set appropriate degrees of freedom. Match specificity to task fragility:

High freedom (text instructions): Multiple approaches valid, decisions depend on context
Medium freedom (pseudocode/parameterized scripts): Preferred pattern exists, some variation OK
Low freedom (specific scripts, exact commands): Operations are fragile, consistency critical

Other principles:

Explain the why - Theory of mind beats rigid MUSTs.
One level of references - SKILL.md links to files; those files don't link further.

简洁是关键。 Claude本身已具备智能——仅添加它不知道的上下文。对每一部分都要质疑：

"Claude真的需要这个解释吗？"
"我能假设Claude知道这个吗？"
"这段内容的token成本是否合理？"

设置合适的自由度等级。 根据任务的稳定性匹配具体程度：

高自由度（文本指令）：多种方法均有效，决策依赖上下文
中自由度（伪代码/参数化脚本）：存在首选模式，允许一定变化
低自由度（特定脚本、精确命令）：操作稳定性要求高，一致性至关重要

其他原则：

解释原因 - 理解背后的逻辑优于生硬的规则。
引用仅一层 - SKILL.md链接到其他文件；这些文件不再进一步链接。

When to Add Scripts

何时添加脚本

Add utility scripts when:

Operations are deterministic (validation, formatting)
Same code would be generated repeatedly
Errors need explicit handling

Use
/create-cli
to build utility CLIs. When a skill needs a CLI script, use

/create-cli

to build it. This ensures the CLI is agent-friendly (non-interactive, parseable output, actionable errors).

Make clear whether Claude should execute or read the script:

Execute (most common): "Run
```
analyze_form.py
```
to extract fields" - more reliable, saves tokens
Read as reference: "See
```
analyze_form.py
```
for the extraction algorithm" - when Claude needs to understand the logic

Don't assume packages are installed. Be explicit about dependencies:

Bad: "Use the pdf library to process the file."
Good: "Install required package:
```
pip install pypdf
```
, then use
```
PdfReader
```
to open files."

在以下情况添加实用脚本：

操作是确定性的（验证、格式化）
相同代码会被重复生成
需要显式处理错误

使用
/create-cli
构建实用CLI。当技能需要CLI脚本时，使用

/create-cli

来构建。这确保CLI对Agent友好（非交互式、输出可解析、错误可处理）。

明确说明Claude应执行还是读取脚本：

执行（最常见）："运行
```
analyze_form.py
```
提取字段" - 更可靠，节省token
作为参考读取："请见
```
analyze_form.py
```
了解提取算法" - 当Claude需要理解逻辑时

不要假设已安装依赖包。 明确说明依赖：

不良示例："使用pdf库处理文件。"
良好示例："安装所需包：
```
pip install pypdf
```
，然后使用
```
PdfReader
```
打开文件。"

MCP Tool References

MCP工具引用

If your skill uses MCP tools, always use fully qualified names to avoid "tool not found" errors:

markdown

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Format:

ServerName:tool_name

- without the server prefix, Claude may fail to locate the tool.

如果技能使用MCP工具，始终使用完全限定名称以避免“工具未找到”错误：

markdown

使用BigQuery:bigquery_schema工具检索表结构。
使用GitHub:create_issue工具创建议题。

格式：

ServerName:tool_name

- 没有服务器前缀，Claude可能无法定位工具。

Dynamic Context Injection

动态上下文注入

Use dynamic context injection to run shell commands before the skill is sent to Claude. The output replaces the placeholder, so Claude receives actual data, not the command.

Syntax:

Inline: exclamation mark followed by backtick-wrapped command (e.g.,
```
!
```
+
```
`git status`
```
)
Multi-line: open a code fence with three backticks followed by
```
!
```
, then close normally

When to use: You always need the same context upfront (not conditional).

Example - PR summary skill:

A skill that needs PR context would include lines like:

```
- PR diff:
```
followed by inline command for
```
gh pr diff
```
```
- Changed files:
```
followed by inline command for
```
gh pr diff --name-only
```

Example - multi-line environment info:

A skill needing multiple commands would use a fenced block opened with the

modifier, containing commands like

node --version

and

npm --version

on separate lines.

This is preprocessing - Claude only sees the final output, not the commands. Don't use this for conditional logic (if A do X, if B do Y) - those should be regular instructions Claude executes.

使用动态上下文注入在技能发送给Claude之前运行shell命令。输出会替换占位符，因此Claude收到的是实际数据，而非命令。

语法：

内联：感叹号后跟反引号包裹的命令（例如，
```
!
```
+
```
`git status`
```
）
多行：用三个反引号加
```
!
```
打开代码块，正常关闭

适用场景： 你始终需要相同的前置上下文（非条件性）。

示例 - PR总结技能：

需要PR上下文的技能可包含如下内容：

```
- PR差异:
```
后跟内联命令
```
gh pr diff
```
```
- 修改文件:
```
后跟内联命令
```
gh pr diff --name-only
```

示例 - 多行环境信息：

需要多个命令的技能可使用带

修饰符的代码块，包含

node --version

和

npm --version

等命令，每行一个。

这是预处理步骤——Claude仅能看到最终输出，看不到命令。不要将其用于条件逻辑（如果A则执行X，如果B则执行Y）——这些应作为常规指令由Claude执行。

Workflows and Feedback Loops

工作流与反馈循环

Use Workflows for Complex Tasks

复杂任务使用工作流

For multi-step operations, use

TaskCreate

to create one task per step. This prevents derailment after interruptions (hooks, agent results, context compaction).

Key insight: Claude can only read task titles, not descriptions. Put essential information in the title:

Gate conditions: "GATE: steps 1-7 complete — Push and create PR"
Key context: "Run /simplify — wait for ALL agents before proceeding"

Pattern: Gated workflow

Some steps depend on prior steps. Make this explicit in the task title so it's visible after compaction.

markdown

undefined

对于多步骤操作，使用

TaskCreate

为每个步骤创建一个任务。这能防止中断（钩子、Agent结果、上下文压缩）后偏离轨道。

核心要点： Claude只能读取任务标题，无法读取描述。将关键信息放在标题中：

门控条件："GATE: 步骤1-7完成 — 推送并创建PR"
关键上下文："运行/simplify — 等待所有Agent完成后再继续"

模式：门控工作流

某些步骤依赖于前置步骤。在任务标题中明确这一点，以便压缩后仍可见。

markdown

undefined

FIRST: Create your task checklist

第一步：创建任务清单

Before reading anything else, use TaskCreate to create one task per step below. Mark each task completed as you finish it. After any interruption, check your task list to find the next uncompleted step.

Important: Copy each step verbatim as the task

subject

— gate conditions must appear in the subject so they're visible in TaskList after compaction.

Read context and reference files
Create feature branch
Implement core functionality
Run tests and type check
Run /simplify — wait for ALL agents to report back, fix issues, re-run tests
GATE: steps 1-5 complete — Push branch, create PR, run code review
GATE: steps 1-6 complete — Stop and wait for user review
GATE: user approved — Merge PR


**Why this works:**
- Tasks created upfront survive context loss
- Gate conditions in titles prevent premature execution
- "After any interruption, check your task list" recovers state

在阅读其他内容之前，使用TaskCreate为以下每个步骤创建一个任务。完成后标记为已完成。任何中断后，查看任务列表找到下一个未完成的步骤。

重要提示： 逐字复制每个步骤作为任务

subject

——门控条件必须出现在subject中，以便在TaskList压缩后仍可见。

阅读上下文和参考文件
创建特性分支
实现核心功能
运行测试和类型检查
运行/simplify — 等待所有Agent反馈，修复问题，重新运行测试
GATE: 步骤1-5完成 — 推送分支，创建PR，运行代码审查
GATE: 步骤1-6完成 — 停止并等待用户审查
GATE: 用户已批准 — 合并PR


**为何有效：**
- 预先创建的任务可避免上下文丢失
- 标题中的门控条件可防止提前执行
- "任何中断后，查看任务列表"可恢复状态

Implement Feedback Loops

实现反馈循环

For quality-critical operations, build in validation cycles (run check → fix → repeat):

markdown

undefined

对于对质量要求高的操作，内置验证周期（运行检查→修复→重复）：

markdown

undefined

Editing process

编辑流程

Make your edits
Validate immediately:
- With scripts:
```
python scripts/validate.py
```
- Without scripts: Review against checklist in STYLE_GUIDE.md
If validation fails:
- Note specific issues
- Fix them
- Validate again
Only proceed when validation passes


This pattern catches errors early whether you're using code or manual review.

进行编辑
立即验证:
- 使用脚本：
```
python scripts/validate.py
```
- 无脚本：对照STYLE_GUIDE.md中的清单检查
如果验证失败：
- 记录具体问题
- 修复问题
- 再次验证
仅在验证通过后继续


无论使用代码还是人工审查，此模式都能尽早发现错误。

Common Patterns

常见模式

Template Pattern

模板模式

Provide templates for output format. Match strictness to requirements:

markdown

undefined

提供输出格式模板。根据要求匹配严格程度：

markdown

undefined

Report structure

报告结构

ALWAYS use this exact template:

markdown

undefined

始终使用此精确模板：

markdown

undefined

[Title]

[标题]

Executive summary

执行摘要

[One-paragraph overview]

[一段概述]

Key findings

关键发现

Finding 1
Finding 2

发现1
发现2

Recommendations

建议

Action item
Action item

undefined

行动项
行动项

undefined

Examples Pattern

示例模式

Show input/output pairs for skills where output quality depends on examples:

markdown

undefined

对于输出质量依赖示例的技能，展示输入/输出对：

markdown

undefined

Commit message format

提交信息格式

Example 1: Input: Added user authentication with JWT tokens Output:

feat(auth): implement JWT-based authentication

Example 2: Input: Fixed bug where dates displayed incorrectly Output:

fix(reports): correct date formatting in timezone conversion

undefined

示例1： 输入：添加基于JWT令牌的用户认证输出：

feat(auth): implement JWT-based authentication

示例2： 输入：修复日期显示错误的bug 输出：

fix(reports): correct date formatting in timezone conversion

undefined

Conditional Workflow Pattern

条件工作流模式

Guide Claude through decision points:

markdown

undefined

引导Claude完成决策点：

markdown

undefined

Document modification workflow

文档修改工作流

Determine the modification type:

Creating new content? → Follow "Creation workflow" below Editing existing content? → Follow "Editing workflow" below
Creation workflow:
- Use library X
- Build from scratch
- Export to format
Editing workflow:
- Unpack existing document
- Modify directly
- Validate after each change

undefined

确定修改类型：

创建新内容？ → 遵循下方“创建工作流” 编辑现有内容？ → 遵循下方“编辑工作流”
创建工作流：
- 使用库X
- 从头构建
- 导出为指定格式
编辑工作流：
- 解压现有文档
- 直接修改
- 每次修改后验证

undefined

Review Checklist

审查清单

Anti-Patterns

反模式

Drafting before understanding - The skill will be generic and miss important cases.
Over-engineering - Start minimal; add complexity only when needed.
Vague descriptions - "Helps with X" doesn't trigger; be specific.
Deep nesting - Claude may only partially read nested references.
Time-sensitive content - "After August 2025, use X" will rot.
Offering too many options - "Use pypdf, or pdfplumber, or PyMuPDF..." is confusing. Provide a default with an escape hatch for edge cases.
Batching questions - Hides dependencies; each answer should inform the next.
Asking without a recommendation - You're the designer, not a form.
Asking what could be read - Skim referenced files, attached transcripts, or the existing skill before asking the user.

未理解就起草 - 技能会过于通用，遗漏重要场景。
过度设计 - 从最简版本开始；仅在需要时添加复杂度。
模糊描述 - “帮助处理X”无法触发；需具体明确。
深层嵌套 - Claude可能仅部分读取嵌套引用。
时效性内容 - “2025年8月后使用X”会失效。
提供过多选项 - “使用pypdf、pdfplumber或PyMuPDF……”会造成混淆。提供默认方案，并为边缘情况留好退路。
批量提问 - 隐藏依赖关系；每个答案应指导下一个问题。
只提问不给出推荐 - 你是设计者，不是表单。
本可读取却提问 - 在询问用户前，先浏览参考文件、附件记录或现有技能文档。