skill-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Builder

Unified, security-first skill builder.

This skill is intentionally opinionated:

Prefer no new skill if a simpler change works (project docs, a script, or a small snippet).
When you do create a skill, make it boring, testable, and hard to misuse.
Keep one clear router and avoid overlapping triggers across skills.

统一的、安全优先的Skill Builder。

本Skill带有明确的设计倾向：

如果更简单的修改就能解决问题（如项目文档、脚本或小代码片段），则优先不创建新Skill。
当确实需要创建Skill时，要使其简洁、可测试且难以被误用。
保持单一清晰的路由，避免不同Skill之间的触发词重叠。

Operation Router

操作路由

User intent	Operation	Output
create/build/make/new skill	CREATE	new skill folder + `SKILL.md` + `README.md`
update/modify/improve skill	UPDATE	minimal diff, keep triggers stable
delete/remove skill	DELETE	remove skill + update repo index
add content/route/workflow to skill	ADD	new router row + new section file (when needed)
validate skill	VALIDATE	checklist results + fixes
rename skill	RENAME	safe rename + reference updates

用户意图	操作	输出
create/build/make/new skill	CREATE	new skill folder + `SKILL.md` + `README.md`
update/modify/improve skill	UPDATE	minimal diff, keep triggers stable
delete/remove skill	DELETE	remove skill + update repo index
add content/route/workflow to skill	ADD	new router row + new section file (when needed)
validate skill	VALIDATE	checklist results + fixes
rename skill	RENAME	safe rename + reference updates

What "Correct" Means

什么是“正确”的标准

This skill treats "correct" as:

Conforms to the Agent Skills spec (directory +
```
SKILL.md
```
frontmatter constraints).
Uses progressive disclosure: small
```
SKILL.md
```
, deeper docs in
```
references/
```
.
Has unambiguous activation: specific description + non-overlapping triggers.
Is safe: no secrets, no default-destructive commands, tool usage is scoped.

本Skill将“正确”定义为：

符合Agent Skills规范（目录 +
```
SKILL.md
```
前置约束）。
采用渐进式披露：简洁的
```
SKILL.md
```
，详细文档放在
```
references/
```
目录中。
激活条件明确：具体的描述 + 无重叠的触发词。
安全性：不包含敏感信息，无默认破坏性命令，工具使用范围受限。

Phase 0: First-Principles Check (Mandatory)

阶段0：基本原则检查（必填）

Run this before ANY CREATE/UPDATE:

QUESTION: what problem, for who, measured how?
DELETE: can an existing component/skill/command solve it?
SIMPLIFY: smallest change that works (often a project instruction file)
ACCELERATE: only after (2) and (3)
AUTOMATE: create a component only if it will be reused

If the answer is "no skill", propose:

a README section
a small script
a usage snippet users can copy

在执行任何CREATE/UPDATE操作前，必须运行以下检查：

问题：要解决什么问题？面向谁？如何衡量效果？
淘汰：现有组件/Skill/命令能否解决该问题？
简化：采用最小可行的修改方案（通常是项目说明文件）
加速：仅在完成(2)和(3)后再考虑
自动化：仅当组件会被重复使用时才创建

如果结论是“不需要Skill”，则建议：

新增README章节
编写小型脚本
提供用户可复制的使用片段

Phase 1: Detect Target + Name

阶段1：检测目标与命名

Target repository layout

目标仓库结构

This repo layout:

```
/<skill-name>/SKILL.md
```
(home/router)
```
/<skill-name>/README.md
```
(short overview)
optional:
```
/<skill-name>/references/*.md
```
(split workflows)

本仓库结构：

```
/<skill-name>/SKILL.md
```
（主页/路由）
```
/<skill-name>/README.md
```
（简短概述）
可选：
```
/<skill-name>/references/*.md
```
（拆分的工作流）

Spec Rules (Agent Skills)

规范规则（Agent Skills）

From the Agent Skills specification:

Skill folder name must match
```
name
```
.
```
name
```
constraints: 1-64 chars; lowercase letters/numbers/hyphens; no leading/trailing
```
-
```
; no
```
--
```
.
```
description
```
should say what + when; max 1024 chars.
Optional frontmatter fields you may include:
```
license
```
,
```
compatibility
```
,
```
metadata
```
,
```
allowed-tools
```
.

Reference: https://agentskills.io/specification

来自Agent Skills规范：

Skill文件夹名称必须与
```
name
```
字段匹配。
```
name
```
约束：1-64个字符；仅包含小写字母/数字/连字符；首尾不能是
```
-
```
；不能包含
```
--
```
。
```
description
```
应说明功能与适用场景；最大1024字符。
可包含的可选前置字段：
```
license
```
、
```
compatibility
```
、
```
metadata
```
、
```
allowed-tools
```
。

参考链接：https://agentskills.io/specification

Naming

命名规则

Use kebab-case (
```
my-skill-name
```
).
Avoid generic names (
```
tools
```
,
```
helper
```
).
Prefer verbs for commands (
```
review-pr
```
,
```
sync-main
```
).

使用kebab-case格式（如
```
my-skill-name
```
）。
避免使用通用名称（如
```
tools
```
、
```
helper
```
）。
命令类Skill优先使用动词（如
```
review-pr
```
、
```
sync-main
```
）。

Phase 2: CREATE Flow

阶段2：CREATE流程

Inputs (minimum)

最小输入项

Name
Goal + non-goals
Triggers (what user says)
Allowed tools (tightest possible)

名称
目标与非目标
触发词（用户会说的内容）
允许使用的工具（尽可能窄的范围）

CREATE Steps

CREATE步骤

Discover existing conventions (look at other skills in the repo).
Draft a micro-spec (goal/non-goals, routing, tool boundaries).
Create
```
/<skill-name>/SKILL.md
```
with:
- front matter (name/description + triggers)
- router table
- safety rules
- minimal workflows (or links to
```
references/
```
  )
Create
```
/<skill-name>/README.md
```
with install + entry points.
Validate (see Validation).
If the repo has an index of skills (commonly a
```
README.md
```
), add/update the entry.

发现现有约定（查看仓库中的其他Skill）。
草拟微型规范（目标/非目标、路由、工具边界）。
创建
```
/<skill-name>/SKILL.md
```
，包含：
- 前置内容（name/description + 触发词）
- 路由表
- 安全规则
- 最简工作流（或指向
```
references/
```
  的链接）
创建
```
/<skill-name>/README.md
```
，包含安装说明和入口点。
验证（参见验证部分）。
如果仓库有Skill索引（通常是
```
README.md
```
），添加/更新对应条目。

Output Contract (CREATE)

CREATE输出约定

When creating a skill, always return:

Files created/edited (paths only)
Trigger phrases added
One minimal "smoke test" prompt (how to activate it)
Validation result (pass/fail + what to fix)

创建Skill时，必须返回：

创建/编辑的文件（仅路径）
添加的触发词
一个最简“冒烟测试”提示词（如何激活该Skill）
验证结果（通过/失败 + 需修复的问题）

Phase 3: UPDATE Flow

阶段3：UPDATE流程

Read current skill.
Identify actual user goal (avoid refactors).
Apply minimal diff.
Re-run validation checklist.
Keep triggers stable unless explicitly requested.

读取当前Skill内容。
明确用户的实际目标（避免不必要的重构）。
应用最小化差异修改。
重新运行验证检查清单。
除非用户明确要求，否则保持触发词稳定。

Phase 4: DELETE Flow

阶段4：DELETE流程

Confirm skill folder.
Identify dependents (root
```
README.md
```
, other skill references).
Remove skill and update references.
Provide rollback note (restore from git).

确认Skill文件夹。
识别依赖项（根目录
```
README.md
```
、其他Skill的引用）。
删除Skill并更新所有引用。
提供回滚说明（从git恢复）。

Phase 5: ADD Content to a Skill

阶段5：向Skill添加内容

Rules for skill growth:

Never duplicate trigger phrases across multiple skills in the same install.
Route by intent first, then load deeper sections.
Keep SKILL.md readable: prefer short tables + stable templates.

Add steps:

Add one new router row.
Add the minimal new procedure.
If it grows: split into
```
references/<topic>.md
```
.
Add/adjust examples.
Re-check cross-skill consistency.

Skill扩展规则：

同一安装环境下，多个Skill之间绝不能有重复的触发词。
优先按意图路由，再加载深层内容。
保持SKILL.md的可读性：优先使用简短表格和稳定模板。

添加步骤：

添加一条新的路由行。
添加最简的新流程。
如果内容过长：拆分到
```
references/<topic>.md
```
中。
添加/调整示例。
重新检查跨Skill一致性。

Validation

验证

Skill Validation Checklist

Skill验证检查清单

Front matter includes
```
name
```
and
```
description
```
.
Has a router (how to decide what to do).
Defines what is safe to run without confirmation vs requires confirmation.
No secrets; no links to private paths.
No unscoped destructive instructions.
Trigger hygiene: no overlapping triggers with existing skills in the repo.
Docs split: if SKILL.md becomes long, move workflows into
```
references/
```
.

前置内容包含
```
name
```
和
```
description
```
字段。
包含路由（用于决策执行逻辑）。
定义无需确认即可安全运行的操作与需要确认的操作。
无敏感信息；无指向私有路径的链接。
无无范围限制的破坏性指令。
触发词规范：与仓库中现有Skill无重叠的触发词。
文档拆分：如果SKILL.md过长，将工作流移至
```
references/
```
目录。

Spec Validation (Recommended)

规范验证（推荐）

If you have the reference validator available (optional), run:

bash

skills-ref validate ./<skill-name>

If not available, validate manually using the rules in "Spec Rules" above.

如果有可用的参考验证工具（可选），运行：

bash

skills-ref validate ./<skill-name>

如果工具不可用，使用上述“规范规则”中的内容手动验证。

Tool Safety

工具安全性

Prefer Read/Glob/Grep before Bash.
If Bash is needed, scope it (git-only, or specific commands).
Never recommend
```
rm -rf
```
,
```
git reset --hard
```
,
```
push --force
```
as defaults.

优先使用Read/Glob/Grep而非Bash。
如果必须使用Bash，限定其范围（仅git命令或特定命令）。
绝不推荐将
```
rm -rf
```
、
```
git reset --hard
```
、
```
push --force
```
作为默认命令。

Templates

模板

Skill Front Matter

Skill前置内容

yaml

---
name: my-skill
description: Describe what the skill does and when to use it. Include trigger phrases.
compatibility: Optional. Mention required system tools, network needs, or target environments.
metadata:
  version: "0.1"
allowed-tools: Optional. Space-delimited list. Prefer the narrowest set possible.
---

yaml

---
name: my-skill
description: Describe what the skill does and when to use it. Include trigger phrases.
compatibility: Optional. Mention required system tools, network needs, or target environments.
metadata:
  version: "0.1"
allowed-tools: Optional. Space-delimited list. Prefer the narrowest set possible.
---

Progressive Disclosure Pattern

渐进式披露模式

Keep

SKILL.md

as:

Frontmatter
Router table
Safety rules
Short workflows
Links to
```
references/*.md
```
for deep details

保持

SKILL.md

结构如下：

前置内容
路由表
安全规则
简短工作流
指向
```
references/*.md
```
的深层详情链接

References

参考资料

```
references/checklist.md
```
(authoring checklist)
```
references/templates.md
```
(copy/paste templates)
```
references/validation.md
```
(validation flow + trigger hygiene)

```
references/checklist.md
```
（作者检查清单）
```
references/templates.md
```
（可复制粘贴的模板）
```
references/validation.md
```
（验证流程 + 触发词规范）

What This Skill Is For (Practical Examples)

本Skill的适用场景（实用示例）

"Create a skill that scaffolds new skills" → create a skill + templates + validation.
"Update my git workflow" → improve the router + split workflows into
```
references/
```
.
"Make skills consistent across repos" → enforce naming/triggers/tool boundaries.

“创建一个用于生成新Skill的Skill” → 创建Skill + 模板 + 验证。
“更新我的git工作流” → 优化路由 + 将工作流拆分至
```
references/
```
目录。
“确保不同仓库中的Skill保持一致” → 强制执行命名/触发词/工具边界规则。