skill-maker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create, Audit, or Consolidate Skills

创建、审核或合并技能

Create agent skills following the Agent Skills open standard.

What do you need to do?

Audit an existing skill — Review, improve, or debug a SKILL.md
Create a new skill — Interview, draft, and review from scratch
Consolidate skills — Merge multiple skills into fewer

Wait for response before proceeding. </intake>

Response	Workflow
1, "audit", "review", "check", "fix", "improve"	Audit Workflow (Step 1–4 in this file)
2, "create", "write", "build", "new", "draft"	Phases 1–5 (Interview → Draft → Description → Scripts → Review) in this file
3, "consolidate", "merge", "combine"	`references/consolidation-guide.md` — return to Phase 5 for final checklist

</routing>

遵循Agent Skills开放标准创建Agent技能。

你需要执行什么操作？

审核现有技能 — 评审、改进或调试SKILL.md
创建新技能 — 从访谈、起草到评审的全流程
合并技能 — 将多个技能整合为更少的数量

请等待用户回复后再继续。 </intake>

回复内容	工作流
1、"audit"、"review"、"check"、"fix"、"improve"	审核工作流（本文档中的步骤1–4）
2、"create"、"write"、"build"、"new"、"draft"	本文档中的阶段1–5（访谈 → 起草 → 描述优化 → 脚本编写 → 评审）
3、"consolidate"、"merge"、"combine"	`references/consolidation-guide.md` — 完成后返回阶段5进行最终检查

</routing>

Audit Workflow

审核工作流

Use this workflow when reviewing, improving, or debugging an existing skill.

当你需要评审、改进或调试现有技能时，使用此工作流。

Step 1: Locate and read the skill

步骤1：定位并读取技能

Read the full SKILL.md and list all files in the skill directory (

references/

scripts/

templates/

assets/

完整读取SKILL.md，并列出技能目录中的所有文件（

references/

、

scripts/

、

templates/

、

assets/

）。

Step 2: Run the audit checklist

步骤2：执行审核检查清单

Check each category. Note issues as you go.

Frontmatter:

```
name
```
matches the directory name, lowercase+hyphens, max 64 chars
```
description
```
is under 1024 chars, non-empty, third person
```
description
```
includes trigger phrases (not just a summary of what the skill does)
```
description
```
covers edge phrasings users would actually say

Structure:

SKILL.md body is under 500 lines
Essential principles are inline in SKILL.md (not only in a reference file)
All referenced files exist (check every path in the SKILL.md)
References are one level deep (no nested chains: A → B → C)

Content quality:

No rigid ALWAYS/NEVER rules without reasoning (explain WHY)
No explanations of things the agent already knows from training
Steps are specific and verifiable (not "handle errors appropriately")
Success criteria are observable and testable
Examples use fake data where appropriate

Router pattern (if applicable):

Intake question asks what the user wants before routing
Router table maps commands to reference files
All referenced workflow/reference files exist
Essential principles are in SKILL.md, not only in sub-command references
If skill has multiple semantic sections, consider XML tags for structure (see
```
references/xml-structure-guide.md
```
)

Scripts (if present):

Scripts have shebangs,
```
--help
```
, and structured output
No interactive prompts (all input via flags/env/stdin)
Cross-platform paths (pathlib, no hardcoded separators)
Error messages explain what went wrong and what to do

Read

references/anti-patterns.md

for the full catalog of common failures.

检查每个类别，记录发现的问题。

前置元数据：

```
name
```
与目录名称匹配，仅使用小写字母和连字符，最长64字符
```
description
```
长度不超过1024字符，非空且使用第三人称表述
```
description
```
包含触发短语（不只是技能功能的总结）
```
description
```
覆盖用户实际可能使用的边缘表述

结构：

SKILL.md主体内容不超过500行
核心原则内联在SKILL.md中（不仅存于参考文件）
所有引用的文件均存在（检查SKILL.md中的每一条路径）
引用仅为一级深度（无嵌套链式引用：A → B → C）

内容质量：

无无理由的绝对规则（需解释原因）
无需解释Agent已通过训练掌握的内容
步骤具体且可验证（避免“适当处理错误”这类表述）
成功标准可观察、可测试
示例酌情使用虚假数据

路由模式（如适用）：

引导提问在路由前询问用户需求
路由表将命令映射到参考文件
所有引用的工作流/参考文件均存在
核心原则存于SKILL.md，而非仅在子命令参考文件中
若技能包含多个语义模块，考虑使用XML标签构建结构（详见
```
references/xml-structure-guide.md
```
）

脚本（如存在）：

脚本包含shebang、
```
--help
```
参数和结构化输出
无交互式提示（所有输入通过标志位/环境变量/标准输入传递）
使用跨平台路径（pathlib，无硬编码分隔符）
错误信息说明问题所在及解决方法

阅读

references/anti-patterns.md

查看常见问题的完整列表。

Step 3: Generate the report

步骤3：生成审核报告

Present findings grouped by severity:

Critical — skill won't trigger or produces wrong output
Important — structural issues, missing files, spec violations
Minor — style, conciseness, optimization opportunities

For each finding, state the issue, cite the specific line or section, and recommend a fix.

按严重性分组呈现发现的问题：

严重问题 — 技能无法触发或输出错误结果
重要问题 — 结构问题、文件缺失、违反标准
次要问题 — 风格、简洁性、优化空间

针对每个问题，说明问题内容、引用具体行或章节，并给出修复建议。

Step 4: Offer fixes

步骤4：提供修复方案

Ask the user which findings to fix. Apply changes surgically — don't rewrite sections that aren't broken. Run the Phase 5 review checklist on the modified skill before finishing.

询问用户需要修复哪些问题。精准修改——不要重写无问题的部分。修改完成后，使用阶段5的评审检查清单验证技能。

Phase 1: Interview

阶段1：访谈

Interview the user about every aspect of this skill until reaching shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

与用户深入讨论技能的各个方面，直至达成共识。逐步梳理设计树的每个分支，逐一解决决策间的依赖关系。每个问题都需提供你的推荐答案。

Interview cadence

访谈节奏

Ask one question at a time. Wait for the answer before asking the next. Adapt follow-ups based on what you learn. Each question should provide clear benefit toward building a better skill — cut questions the codebase can answer for you.

If a question can be answered by exploring the codebase, explore the codebase instead of asking.

Focus areas, roughly in order:

Purpose and audience. What task does this skill cover? What specific problem does it solve? What does the user do today without it?
Scope boundaries. What should this skill NOT do? What adjacent tasks belong to other skills?
Input/output. What does the user provide? What does the skill produce? Specific formats?
Edge cases. What goes wrong? Common mistakes? Gotchas for new users?
Success criteria. How do you know the skill worked correctly?
What can be scripted? Look for deterministic operations that should be code, not LLM instructions. Scripts are cheaper, faster, and more reliable.
References needed? Domain knowledge too large for SKILL.md that should live in separate files?
Existing patterns. Similar skills or workflows to draw from? Check the codebase.
Platform constraints. macOS, Windows, and Linux? Scripts must handle path separators, temp directories, and shell differences.
External services and APIs. Does the skill call external APIs or services? If yes, read
```
references/api-skill-patterns.md
```
— it covers credential handling, schema discovery, instance-specific values, and error placement.

一次只问一个问题，等待回复后再提出下一个。根据所得信息调整后续问题。每个问题都应有助于构建更优质的技能——删除可通过代码库自行解答的问题。

若问题可通过探索代码库解答，则直接探索代码库，无需询问用户。

重点关注领域大致顺序：

用途与受众：该技能覆盖什么任务？解决什么具体问题？用户当前无此技能时如何操作？
范围边界：该技能不应该做什么？哪些相关任务属于其他技能？
输入/输出：用户提供什么内容？技能生成什么内容？具体格式是什么？
边缘情况：可能出现哪些问题？常见错误？新用户易踩的坑？
成功标准：如何判断技能已正确执行？
可脚本化内容：寻找应通过代码实现的确定性操作，而非LLM指令。脚本成本更低、速度更快、更可靠。
所需参考资料：领域知识过于庞大，无法放入SKILL.md，需存于单独文件？
现有模式：是否有可借鉴的类似技能或工作流？检查代码库。
平台限制：是否支持macOS、Windows和Linux？脚本需处理路径分隔符、临时目录和Shell差异。
外部服务与API：技能是否调用外部API或服务？若是，阅读
```
references/api-skill-patterns.md
```
——其中涵盖凭证处理、 schema发现、实例特定值和错误处理位置。

Architecture decision tree

架构决策树

After the interview questions above, decide the architecture. Most skills are simple — only escalate when the answers demand it.

Question 1: How many distinct things can a user want to do?

One specific thing → Simple skill (single SKILL.md, under 200 lines)
Multiple things with shared principles → continue to Q2

Question 2: Is there shared domain knowledge across those operations?

No, each operation is self-contained → Simple skill (or multiple separate simple skills)
Yes, multiple operations share knowledge → Router skill (SKILL.md +
```
references/
```
)

Question 3: Does it cover a full lifecycle (build, debug, test, ship)?

No → Router skill is sufficient
Yes → Domain expertise skill (exhaustive references, full lifecycle workflows)

What you're building	Pattern
"A skill that commits with a conventional message"	Simple
"A skill that manages PRs — create, review, merge, close"	Router
"A skill for building and shipping macOS apps"	Domain expertise
"A skill that audits other skills"	Simple (upgrade to Router if it grows)

For Router and Domain expertise patterns, also ask:

Does the skill need project-level context? If every command needs the same background, design a context file pattern with a loader script.
Are there mandatory setup gates? Steps that must pass before any work begins. Gates prevent generic output.
Does behavior vary by task type? If so, design a register/mode system that classifies the task first, then loads different references.

Read

references/architecture-patterns.md

for implementation details of each pattern.

Consolidation signal check: If the interview reveals the new skill overlaps significantly with existing skills (shared scripts, cross-references, linear pipeline), consider consolidating instead of creating. Read

references/consolidation-guide.md

for the signals and workflow.

Do not proceed to Phase 2 until the user confirms the scope is complete.

完成上述访谈问题后，确定技能架构。大多数技能较为简单——仅在答案要求时升级架构。

问题1：用户可能需要执行多少种不同操作？

仅一种特定操作 → 简单技能（单个SKILL.md，不超过200行）
多种操作且共享核心原则 → 继续问题2

问题2：这些操作是否共享领域知识？

否，每个操作独立 → 简单技能（或多个独立的简单技能）
是，多个操作共享知识 → 路由技能（SKILL.md +
```
references/
```
）

问题3：是否覆盖完整生命周期（构建、调试、测试、发布）？

否 → 路由技能已足够
是 → 领域专业技能（详尽参考资料、全生命周期工作流）

构建目标	模式
"生成符合约定式规范的提交信息的技能"	简单
"管理PR的技能——创建、评审、合并、关闭"	路由
"构建和发布macOS应用的技能"	领域专业
"审核其他技能的技能"	简单（若规模扩大可升级为路由）

对于路由和领域专业模式，还需询问：

技能是否需要项目级上下文？ 若每个命令都需要相同背景信息，设计带加载脚本的上下文文件模式。
是否有强制设置检查？ 任何工作开始前必须完成的步骤。检查可避免因缺失上下文导致的通用输出。
行为是否因任务类型而异？ 若是，设计注册/模式系统，先对任务分类，再加载不同参考资料。

阅读

references/architecture-patterns.md

查看每种模式的实现细节。

合并信号检查： 若访谈显示新技能与现有技能存在显著重叠（共享脚本、交叉引用、线性流程），考虑合并而非创建新技能。阅读

references/consolidation-guide.md

查看信号和工作流。

在用户确认范围完整前，请勿进入阶段2。

Phase 2: Draft the SKILL.md

阶段2：起草SKILL.md

Write the skill following the spec. Read

references/spec-guide.md

for the full format reference before drafting.

Starter templates: Use

templates/simple-skill.md

for single-purpose skills,

templates/router-skill.md

for multi-command skills using markdown headings, or

templates/router-skill-xml.md

for multi-command skills using XML structure. Copy the template as a starting point, then customize.

遵循标准编写技能。起草前阅读

references/spec-guide.md

查看完整格式参考。

起始模板： 单用途技能使用

templates/simple-skill.md

，多命令技能使用

templates/router-skill.md

（基于Markdown标题）或

templates/router-skill-xml.md

（基于XML结构）。复制模板作为起点，再进行自定义。

Frontmatter

前置元数据

yaml

---
name: skill-name        # lowercase, hyphens, max 64 chars
description: |           # max 1024 chars — this is the ONLY triggering mechanism
  What the skill does. Use when [specific triggers].
  Also use when [additional triggers].
---

The description must be slightly "pushy" — agents tend to undertrigger. Include both what the skill does AND specific phrases/contexts that should activate it.

yaml

---
name: skill-name        # 小写字母、连字符，最长64字符
description: |           # 最长1024字符——这是唯一的触发机制
  技能功能说明。在[特定触发场景]时使用。
  也可在[其他触发场景]时使用。
---

描述需略带“主动性”——Agent往往触发不足。需同时包含技能功能和应触发技能的具体短语/场景。

Body structure

主体结构

Follow progressive disclosure — three loading levels:

Metadata (~100 tokens):
```
name
```
and
```
description
```
loaded at startup for all skills
Instructions (< 500 lines): Full SKILL.md body loaded when skill activates
Resources (as needed):
```
references/
```
,
```
scripts/
```
,
```
assets/
```
loaded only when required

Keep the SKILL.md body under 500 lines. If approaching this limit, split domain-specific content into

references/

files with clear pointers about when to read them.

遵循渐进式披露——三个加载层级：

元数据（约100令牌）：
```
name
```
和
```
description
```
在启动时加载，适用于所有技能
指令（<500行）：技能激活时加载完整SKILL.md主体
资源（按需加载）：仅在需要时加载
```
references/
```
、
```
scripts/
```
、
```
assets/
```

SKILL.md主体内容需控制在500行以内。若接近此限制，将领域特定内容拆分至

references/

文件，并明确标注读取时机。

Deduplication check

去重检查

Before writing domain knowledge into a new reference file, check if it already exists in another reference. Shared data (exit criteria, field mappings, workflow rules) must live in exactly one file. New references should point to the existing source — not embed a copy.

Common trap: a new sub-command reference duplicates tables from an existing reference because it "needs them for context." Instead, add a one-line pointer: "Load

references/workflows.md

for exit criteria per status."

Exception: intentional duplication. When two sub-commands need the same query pattern but referencing each other would create a transitive loading chain (A → B → C), duplicate the pattern and add a note: "Same query pattern as X.md Step N — duplicated here to avoid transitive loading." This is cheaper than forcing the agent to load an unrelated file.

在将领域知识写入新参考文件前，检查是否已存在于其他参考文件中。共享数据（退出标准、字段映射、工作流规则）必须仅存于一个文件。新参考文件应指向现有源——而非嵌入副本。

常见误区：新子命令参考文件因“需要上下文”而重复现有参考文件中的表格。正确做法是添加一行指向：“加载

references/workflows.md

查看各状态对应的退出标准。”

例外：有意重复 当两个子命令需要相同查询模式，但相互引用会导致传递性加载链（A → B → C）时，可重复该模式并添加注释：“与X.md步骤N的查询模式相同——此处重复以避免传递性加载。” 这比强制Agent加载无关文件更高效。

Writing patterns

编写模式

Imperative form: "Run the command" not "You should run the command"
Explain WHY, not just what: Avoid rigid ALWAYS/NEVER rules without reasoning. Agents generalize from principles better than from rigid rules. Instead of "ALWAYS use pdfplumber. NEVER use PyPDF2," write "Use pdfplumber over PyPDF2 — it handles malformed PDFs more gracefully and preserves layout metadata needed for table extraction." Principles adapt to edge cases; rigid rules break.
Don't explain what the agent already knows: Skip basic programming concepts, standard library usage, and well-known tool behavior. Only add context the agent doesn't have — project-specific conventions, non-obvious behavior, domain-specific gotchas. A 30-token code example beats a 150-token explanation of what a library is.
Output templates: Define exact formats when the output structure matters
Concrete examples: Show input → output for non-obvious workflows
Gotchas sections: Common mistakes the agent should avoid
Checklists: Multi-step workflows with validation gates
Conditional loading: "Read
```
references/api-errors.md
```
if the API returns a non-200 status code" — not "see references/ for details"
Absolute bans: When certain patterns are always wrong, use match-and-refuse lists. "If you're about to write X, stop and do Y instead." More effective than vague "be careful" guidance.
Avoid hardcoded thresholds: Don't write arbitrary numbers as rules (e.g., "when you have 3+ sub-commands" or "if more than 5 issues") unless the threshold comes from a real constraint (API limit, spec requirement). Instead, describe the signal that triggers the behavior (e.g., "when you're copying the same text into another sub-command"). Hardcoded numbers feel authoritative but are usually guesses that don't generalize.

Read

references/anti-patterns.md

during drafting to avoid known pitfalls.

祈使语气：使用“运行命令”而非“你应该运行命令”
解释原因，而非仅说明操作：避免无理由的绝对规则。Agent从原则中学习比从刚性规则中学习更擅长泛化。不要写“始终使用pdfplumber，绝不使用PyPDF2”，应写“优先使用pdfplumber而非PyPDF2——它能更优雅地处理格式错误的PDF，并保留表格提取所需的布局元数据。” 原则可适应边缘情况；刚性规则易失效。
无需解释Agent已知内容：跳过基础编程概念、标准库用法和知名工具行为。仅添加Agent不具备的上下文——项目特定约定、非直观行为、领域特定陷阱。30令牌的代码示例胜过150令牌的库功能说明。
输出模板：当输出结构重要时，定义精确格式
具体示例：为非直观工作流展示输入→输出过程
陷阱章节：列出Agent应避免的常见错误
检查清单：带验证节点的多步骤工作流
条件加载：“若API返回非200状态码，读取
```
references/api-errors.md
```
”——而非“详见references/中的内容”
绝对禁止：当某些模式始终错误时，使用匹配拒绝列表。“若你打算编写X，请停止并改为Y。” 这比模糊的“请谨慎”更有效。
避免硬编码阈值：除非阈值来自实际约束（API限制、标准要求），否则不要将任意数字作为规则（如“当你有3个以上子命令时”或“若问题超过5个”）。相反，描述触发行为的信号（如“当你将相同文本复制到另一个子命令时”）。硬编码数字看似权威，但通常是无法泛化的猜测。

起草过程中阅读

references/anti-patterns.md

避免已知误区。

XML structure (router and domain expertise skills)

XML结构（路由和领域专业技能）

Agents parse XML tags more reliably than markdown headings when a skill has semantically distinct sections (principles, intake, routing, references). XML tags create unambiguous containers; markdown headings blend together in long prompts.

Read

references/xml-structure-guide.md

for suggested patterns and anti-patterns.

When XML helps:

Skills with an intake question + routing table + essential principles
Skills where an agent needs to quickly locate a specific section
Skills with inline workflows that need clear start/end boundaries

When markdown is enough:

Simple skills with a single linear workflow
Sequential instructional content (phases, steps) where order matters more than section lookup

当技能包含语义不同的模块（原则、引导、路由、参考）时，Agent解析XML标签比Markdown标题更可靠。XML标签创建明确的容器；Markdown标题在长提示中易混淆。

阅读

references/xml-structure-guide.md

查看推荐模式和反模式。

XML适用场景：

包含引导提问+路由表+核心原则的技能
Agent需快速定位特定章节的技能
包含需明确起止边界的内嵌工作流的技能

Markdown足够的场景：

单一线性工作流的简单技能
顺序式教学内容（阶段、步骤），其中顺序比章节查找更重要

Sub-command router (when applicable)

子命令路由（如适用）

For skills with multiple distinct operations, use a router table in SKILL.md.

xml

<intake>

对于包含多个独立操作的技能，在SKILL.md中使用路由表。

xml

<intake>

What would you like to do?

你想要执行什么操作？

Craft a feature — Build end-to-end
Audit code — Technical quality checks

Wait for response before proceeding. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "craft", "build" | `references/craft.md` | | 2, "audit", "check" | `references/audit.md` | </routing> ```

Back the router with a

scripts/command-metadata.json

as the single source of truth:

json

{
  "craft": {
    "description": "Full build flow. Use when building a new feature end-to-end.",
    "argumentHint": "[feature description]"
  }
}

开发功能 — 端到端构建
审核代码 — 技术质量检查

请等待回复后再继续。 </intake>

<routing> | 回复内容 | 工作流 | |----------|----------| | 1、"craft"、"build" | `references/craft.md` | | 2、"audit"、"check" | `references/audit.md` | </routing> ```

使用

scripts/command-metadata.json

作为命令元数据的唯一来源，为路由提供支持：

json

{
  "craft": {
    "description": "完整构建流程。在端到端开发新功能时使用。",
    "argumentHint": "[功能描述]"
  }
}

Setup gates (when applicable)

设置检查（如适用）

Non-negotiable checks before any file edits. Gates prevent generic output from missing context.

markdown

undefined

任何文件编辑前必须完成的检查。检查可避免因缺失上下文导致的通用输出。

markdown

undefined

Setup (non-optional)

设置（非可选）

Gate	Required check	If fail
Context	Project config loaded via `python scripts/load_context.py`	Run the loader first
Config	Config file exists and is valid	Run `skill-name setup`
Command	Sub-command reference is loaded	Load the reference
Mutation	All gates above pass	Do not edit project files

undefined

检查节点	必需检查项	失败处理
上下文	通过 `python scripts/load_context.py` 加载项目配置	先运行加载脚本
配置	配置文件存在且有效	运行 `skill-name setup`
命令	子命令参考文件已加载	加载参考文件
修改	以上所有检查均通过	不得编辑项目文件

undefined

Register/mode system (when applicable)

注册/模式系统（如适用）

When behavior varies by task type, classify first, then load different references:

markdown

undefined

当行为因任务类型而异时，先分类，再加载不同参考资料：

markdown

undefined

Register

注册

Every task is library (published, API-stable) or application (internal, can break). Identify before acting. Load the matching reference: [references/library.md] or [references/application.md].

undefined

每个任务分为库（已发布、API稳定）或应用（内部、可变更）两类。执行操作前先分类，加载匹配的参考资料：[references/library.md]或[references/application.md]。

undefined

Capability-gating

能力适配

Steps that depend on optional environment capabilities (browser automation, specific CLI tools) must degrade gracefully:

markdown

undefined

依赖可选环境能力（浏览器自动化、特定CLI工具）的步骤需优雅降级：

markdown

undefined

Automated Scan (Capability-Gated)

自动扫描（能力适配）

Run the automated scanner when ALL of these are true:

The target files exist and are readable
The required CLI tool is installed

If unavailable, state in one line that the step is skipped and why. Do not ask the user to install tooling.

undefined

仅当以下所有条件满足时，运行自动扫描器：

目标文件存在且可读
所需CLI工具已安装

若不可用，用一行文字说明跳过该步骤及原因。请勿要求用户安装工具。

undefined

Structured artifacts as handoffs

结构化工件传递

When one command produces output that another consumes, define the artifact structure explicitly. The producing command's reference defines the format; the consuming command's reference says what it expects:

markdown

undefined

当一个命令的输出作为另一个命令的输入时，明确定义工件结构。生成命令的参考文件定义格式；消费命令的参考文件说明预期格式：

markdown

undefined

Plan Structure

计划结构

1. Summary (2-3 sentences) 2. Primary Goal 3. Approach ...

undefined

1. 摘要（2-3句话） 2. 主要目标 3. 实现方案 ...

undefined

Self-critique loops

自我评审循环

For build/implementation commands, mandate inspect-and-fix passes with explicit exit bars:

markdown

undefined

对于构建/实现类命令，强制要求检查修复环节，并明确退出标准：

markdown

undefined

Critique and fix loop

评审与修复循环

After the first pass, write a short self-critique and patch. Repeat until no material issues remain:

Does it match the requirements?
Does it pass the [quality test]?
Check every expected scenario.
Check edge cases.

The exit bar is not "it works." It is: [explicit quality threshold].

undefined

首次完成后，撰写简短的自我评审并修复问题。重复此过程直至无重大问题：

是否符合需求？
是否通过[质量测试]？
检查所有预期场景。
检查边缘情况。

退出标准不是“可用”，而是：[明确的质量阈值]。

undefined

Phase 3: Description Optimization

阶段3：描述优化

The description is the only thing agents see at startup. Read

references/description-guide.md

for the full optimization process.

Quick validation:

Write 5 should-trigger queries (different phrasings, including ones that don't name the skill directly)
Write 5 should-not-trigger queries (near-misses that share keywords but need different skills)
Check: would the description correctly distinguish these?
Revise if needed — broaden for missed triggers, narrow for false triggers
Verify under 1024 characters

For skills with sub-commands, the main description covers the skill broadly. Each sub-command's description in

command-metadata.json

is optimized separately for auto-trigger keyword matching.

描述是Agent启动时唯一可见的内容。阅读

references/description-guide.md

查看完整优化流程。

快速验证：

编写5个应触发查询（不同表述，包括不直接提及技能名称的表述）
编写5个不应触发查询（类似表述但需其他技能处理）
检查：描述能否正确区分这些查询？
必要时修改——扩大范围覆盖遗漏触发场景，缩小范围减少误触发
验证长度不超过1024字符

对于包含子命令的技能，主描述涵盖技能整体。

command-metadata.json

中每个子命令的描述需单独优化，以实现自动触发的关键词匹配。

Phase 4: Scripts

阶段4：脚本编写

Read

references/scripts-guide.md

for the full guide.

Bias toward scripts. Every deterministic operation should be a script, not an instruction. Scripts are cheaper (no LLM tokens), faster (no reasoning), and more reliable (no hallucination).

For each piece of the skill's workflow, ask: "Could a script do this?" If yes, write the script.

Should be scripts:

Validation (input format, required fields, schema compliance)
File generation from templates
Data extraction and transformation
API calls with structured responses
Setup and environment checks
Output formatting
Context loading (read project files, resolve paths, return JSON)
Pin/unpin shortcuts (create/remove command aliases)
Cleanup (remove deprecated files after skill updates)

Should stay as instructions:

Deciding between architectural approaches
Reviewing code for quality or style
Explaining tradeoffs to the user
Creative writing or design decisions
Interview/discovery conversations

Key patterns:

Python without dependencies: stdlib only,
```
argparse
```
for CLI parsing
Python with dependencies: PEP 723 inline metadata with
```
uv run
```
All scripts: Structured output (JSON when piped), clear exit codes, descriptive
```
--help
```

阅读

references/scripts-guide.md

查看完整指南。

优先使用脚本。所有确定性操作都应通过脚本实现，而非指令。脚本成本更低（无需LLM令牌）、速度更快（无需推理）、更可靠（无幻觉）。

针对技能工作流的每个环节，询问：“能否通过脚本实现？” 若可以，编写脚本。

应脚本化的内容：

验证（输入格式、必填字段、 schema合规性）
基于模板生成文件
数据提取与转换
带结构化响应的API调用
设置与环境检查
输出格式化
上下文加载（读取项目文件、解析路径、返回JSON）
固定/取消快捷方式（创建/删除命令别名）
清理（技能更新后删除废弃文件）

应保留为指令的内容：

架构方案决策
代码质量或风格评审
向用户解释权衡
创意写作或设计决策
访谈/探索对话

核心模式：

无依赖Python：仅使用标准库，
```
argparse
```
处理CLI解析
带依赖Python：使用PEP 723内联元数据配合
```
uv run
```
所有脚本：结构化输出（管道传输时使用JSON）、明确退出码、详尽
```
--help
```
说明

Context loader pattern

上下文加载器模式

For skills that need project-level context, write a loader script:

The script should follow all standard patterns:

argparse

with

--help

, structured JSON output (pretty when interactive, compact when piped), clear exit codes (0 = found, 1 = missing),

pathlib

for cross-platform paths, and stdlib-only imports. See the "Context File System" section in

references/architecture-patterns.md

for a skeleton.

The SKILL.md references it: "Load context via

python scripts/load_context.py

. Consume the full JSON output. Never pipe through

head

tail

, or

grep

对于需要项目级上下文的技能，编写加载脚本：

脚本需遵循所有标准模式：

argparse

带

--help

参数、结构化JSON输出（交互时格式化，管道传输时紧凑）、明确退出码（0 = 找到，1 = 缺失）、

pathlib

处理跨平台路径、仅使用标准库导入。详见

references/architecture-patterns.md

中的“上下文文件系统”章节获取框架。

SKILL.md中引用脚本：“通过

python scripts/load_context.py

加载上下文。使用完整JSON输出。切勿通过

head

、

tail

或

grep

管道传输。”

Phase 5: Review

阶段5：评审

Before presenting the final skill, verify against this checklist:

提交最终技能前，对照以下检查清单验证：

Basics

基础项

```
name
```
is lowercase, hyphens only, max 64 chars
```
description
```
is under 1024 chars and includes trigger phrases
```
description
```
is slightly pushy — covers edge phrasings that should activate the skill
SKILL.md body is under 500 lines
Instructions use imperative form

```
name
```
为小写字母+连字符，最长64字符
```
description
```
长度不超过1024字符且包含触发短语
```
description
```
略带主动性——覆盖应触发技能的边缘表述
SKILL.md主体内容不超过500行
指令使用祈使语气

Architecture (if applicable)

架构（如适用）

Sub-commands have a router table with clear routing rules
```
command-metadata.json
```
is the single source of truth for command descriptions
Setup gates are defined with fail actions for each gate
Register/mode system classifies before loading references
Capability-gated steps degrade gracefully with one-line skip reasons
Router/domain skills with distinct sections (intake, routing, principles) consider XML tags for clarity (
```
references/xml-structure-guide.md
```
)

子命令有带明确规则的路由表
```
command-metadata.json
```
是命令描述的唯一来源
定义了设置检查及每个检查的失败处理
注册/模式系统在加载参考资料前先分类
能力适配步骤优雅降级，用一行文字说明跳过原因
包含独立模块（引导、路由、原则）的路由/领域技能考虑使用XML标签提升清晰度（
```
references/xml-structure-guide.md
```
）

References

参考资料

Domain knowledge split into
```
references/
```
with clear "when to read" pointers
Each reference is self-contained — no transitive loading (see
```
spec-guide.md
```
→ Reference Architecture)
Reference loading is conditional, not eager ("Read X if Y happens")
Shared concerns (auth, config) extracted into their own reference, not embedded in a consumer
Error handling lives in the reference for the tool that produces the error
Multi-approach skills include a decision table routing to the correct reference
No browser-only tools referenced (Postman, API consoles, OAuth login pages)

领域知识拆分至
```
references/
```
，并明确标注“读取时机”
每个参考文件独立——无传递性加载（详见
```
spec-guide.md
```
→ 参考架构）
参考资料按需加载，而非预加载（“当Y发生时读取X”）
共享关注点（认证、配置）提取至独立参考文件，而非嵌入消费端
错误处理存于产生错误的工具对应的参考文件中
多方案技能包含决策表，路由至正确参考文件
无仅支持浏览器的工具引用（Postman、API控制台、OAuth登录页面）

Scripts

脚本

Scripts (if any) have shebangs, structured output, and
```
--help
```
Context loader returns JSON, handles missing files, resolves fallback paths
Scripts are cross-platform (pathlib, tempfile, no hardcoded paths)
Scripts are idempotent — safe to re-run

脚本（若有）包含shebang、结构化输出和
```
--help
```
上下文加载器返回JSON，处理缺失文件，解析回退路径
脚本跨平台兼容（pathlib、tempfile、无硬编码路径）
脚本具有幂等性——可安全重复运行

API/Service Skills (if applicable)

API/服务技能（如适用）

Consolidation (if merging existing skills)

合并技能（如合并现有技能）

No references to old skill names anywhere in the project (
```
grep -rn
```
the entire repo)
Router intake menus are sequentially numbered (no gaps from removed items)
Script docstrings and
```
--help
```
text reference the new skill name, not the old ones
Reference paths resolve correctly from each file's location (no
```
references/references/
```
nesting)
All example files from old skills are represented in the consolidated examples
Scripts in the same skill use consistent patterns (NO_COLOR, shell flags, TTY checks, exit codes)
README, ADRs, and other docs updated to reflect new skill structure
New description covers all trigger phrases from all old skills' descriptions

项目中无任何对旧技能名称的引用（
```
grep -rn
```
遍历整个仓库）
路由引导菜单按顺序编号（无因删除项导致的空缺）
脚本文档字符串和
```
--help
```
文本引用新技能名称，而非旧名称
参考路径从每个文件的位置解析正确（无
```
references/references/
```
嵌套）
旧技能的所有示例文件均在合并后的示例中体现
同一技能中的脚本使用一致模式（NO_COLOR、Shell标志位、TTY检查、退出码）
README、ADR及其他文档已更新以反映新技能结构
新描述覆盖所有旧技能描述中的触发短语

Quality

质量

No time-sensitive information (URLs to specific versions, dates that will go stale)
Examples use fake data where possible (emails, names, tokens) — see
```
spec-guide.md
```
→ Fake Data in Examples
Consistent terminology throughout
Concrete examples included for non-obvious workflows
Absolute bans defined for patterns that are always wrong
Self-critique loops defined for build/implementation commands with explicit exit bars

<reference_index>

无时间敏感信息（特定版本的URL、过期日期）
示例酌情使用虚假数据（邮箱、姓名、令牌）——详见
```
spec-guide.md
```
→ 示例中的虚假数据
术语前后一致
非直观工作流包含具体示例
明确定义绝对禁止的错误模式
构建/实现类命令定义了带明确退出标准的自我评审循环

<reference_index>

Reference Index

参考资料索引

Reference	Load when...
`references/spec-guide.md`	Drafting a SKILL.md (Phase 2) — full format reference
`references/description-guide.md`	Optimizing the description (Phase 3)
`references/scripts-guide.md`	Writing scripts (Phase 4)
`references/anti-patterns.md`	Drafting or auditing — common failures to avoid
`references/architecture-patterns.md`	Choosing between simple, router, and domain expertise patterns
`references/api-skill-patterns.md`	Skill calls external APIs or services
`references/consolidation-guide.md`	Merging multiple skills into fewer
`references/xml-structure-guide.md`	Deciding on XML vs markdown structure

</reference_index>

参考资料	加载时机...
`references/spec-guide.md`	起草SKILL.md时（阶段2）——完整格式参考
`references/description-guide.md`	优化描述时（阶段3）
`references/scripts-guide.md`	编写脚本时（阶段4）
`references/anti-patterns.md`	起草或审核时——需避免的常见问题
`references/architecture-patterns.md`	选择简单、路由和领域专业模式时
`references/api-skill-patterns.md`	技能调用外部API或服务时
`references/consolidation-guide.md`	将多个技能合并为更少数量时
`references/xml-structure-guide.md`	选择XML或Markdown结构时

</reference_index>