agent-skill-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skill Rules

以 Agent Skills 官方 Step 1–4 为主流程，并在每一步中嵌入平台无关的治理增强项。

The main process follows the official Step 1–4 of Agent Skills, with platform-independent governance enhancements embedded in each step.

Instructions（分步说明）

Instructions (Step-by-Step Explanation)

Step 1：确认目录结构

Step 1: Confirm directory structure

每个 skill 至少包含

SKILL.md

，可选

scripts/

、

references/

、

assets/

。完整格式规范见 references/specification.md（来源：agentskills.io/specification）。

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional
├── references/       # Optional
└── assets/           # Optional

目录名必须与 frontmatter 中的

name

一致（小写、连字符、1–64 字符）。

规则设计时的命名约定（创建/修改 skill 时适用）：除必要外，所有文件名与目录名使用小写。

默认：新建或重命名的文件、目录均使用小写。
「必要」：仅当规范/框架明确要求某命名时不改为小写（如
```
SKILL.md
```
、
```
README.md
```
、
```
Makefile
```
）。强制规范 > 本约定。
不确定时：先查该规范文档；未写明则使用小写。

增强项（不改变主流程）：

在建结构前先识别动作类型：

create / update / refactor / migrate / audit / deprecate

。

根据动作决定是否需要最小结构或完整结构（避免一次性过度创建目录）。
避免深层引用链：后续文档设计默认单层引用。

Each skill contains at least

SKILL.md

, with optional

scripts/

references/

assets/

directories. For the full format specification, see references/specification.md (source: agentskills.io/specification).

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional
├── references/       # Optional
└── assets/           # Optional

The directory name must match the

name

field in frontmatter (lowercase, hyphenated, 1–64 characters).

Naming conventions for rule design (applicable when creating/modifying skills): All file and directory names use lowercase unless necessary.

Default: All newly created or renamed files and directories use lowercase.
"Necessary" case: Do not convert to lowercase only when the specification/framework explicitly requires a certain name (e.g.
```
SKILL.md
```
,
```
README.md
```
,
```
Makefile
```
). Mandatory specifications take precedence over this convention.
When in doubt: Check the specification document first; use lowercase if not specified.

Enhancements (no change to the main process)：

Identify the action type before building the structure:

create / update / refactor / migrate / audit / deprecate

Decide whether to use the minimal structure or full structure according to the action (avoid creating excessive directories at one time).
Avoid deep reference chains: Subsequent documents are designed to use single-layer references by default.

Step 2：编写 frontmatter

Step 2: Write frontmatter

必填两项：

name：与目录名一致，仅
```
a-z
```
、
```
0-9
```
、
```
-
```
，不以
```
-
```
开头或结尾，无
```
--
```
description：做什么 + 何时用，含关键词，1–1024 字符，第三人称

增强项（不改变主流程）：

```
description
```
除"做什么 + 何时用"外，补充触发关键词以提升匹配稳定性。
对维护类动作（update/refactor/migrate/audit/deprecate）也保持可触发语义。
明确平台无关：不在 frontmatter 写入平台私有字段或平台绑定术语。
识别 skill 类型（详见 references/skill-type-taxonomy.md）：判断当前 skill 属于动作型（procedural）还是约束型（declarative），据此调整
```
description
```
写法：
- 动作型：「做什么 + 何时触发」
- 约束型：「约束什么 + 适用范围」
可选：通过
```
metadata.type
```
标注类型（
```
procedural
```
/
```
declarative
```
），便于分类管理。

Two required fields:

name: Consistent with the directory name, only
```
a-z
```
,
```
0-9
```
,
```
-
```
are allowed, cannot start or end with
```
-
```
, no
```
--
```
description: What it does + when to use it, contains keywords, 1–1024 characters, third person

Enhancements (no change to the main process)：

In addition to "what it does + when to use it", add trigger keywords to
```
description
```
to improve matching stability.
Maintain triggerable semantics for maintenance actions (update/refactor/migrate/audit/deprecate).
Explicitly platform-independent: Do not write platform-private fields or platform-bound terms in frontmatter.
Identify skill type (see references/skill-type-taxonomy.md for details): Determine whether the current skill is procedural or declarative, and adjust the writing of
```
description
```
accordingly:
- Procedural: "What it does + when to trigger"
- Declarative: "What it constrains + applicable scope"
Optional: Mark the type through
```
metadata.type
```
(
```
procedural
```
/
```
declarative
```
) for classified management.

Step 3：编写正文

Step 3: Write main content

YAML 之后为 Markdown 正文。根据 skill 类型选择对应的正文组织方式（详见 references/skill-type-taxonomy.md）：

动作型 skill（procedural） — 沿用官方推荐：

Instructions（分步说明）
Examples（输入/输出示例，若适用）
Edge cases（常见边界情况，若适用）

约束型 skill（declarative） — 不硬套步骤格式，改用声明式组织：

核心原则（必须遵守的底线规则）
行为要求（在具体场景下的行为规范，推荐用对照表）
判断标准（如何判断是否违反原则）
反模式（必须避免的行为，含具体示例）

增强项（不改变主流程）：

正文按"核心规则在前、细节下沉 references"组织（渐进式披露）。
同一规则只维护一处，避免
```
SKILL.md
```
与
```
references/
```
重复。
按任务脆弱性选择自由度：高自由度（原则）、中自由度（模式）、低自由度（硬约束）。
维护类任务建议加最小动作表（创建/修改/重构/迁移/审计/弃用）以提升执行一致性。
混合型 skill：识别主导类型，按主导类型组织正文，将次要类型的内容作为补充段落。

The Markdown body follows the YAML section. Choose the corresponding body organization method according to the skill type (see references/skill-type-taxonomy.md for details):

Procedural skill — follow the official recommendation:

Instructions (step-by-step description)
Examples (input/output examples, if applicable)
Edge cases (common boundary cases, if applicable)

Declarative skill — do not force the step format, use declarative organization instead:

Core principles (bottom-line rules that must be followed)
Behavior requirements (behavior specifications in specific scenarios, comparison tables are recommended)
Judgment criteria (how to judge whether the principle is violated)
Anti-patterns (behaviors that must be avoided, including specific examples)

Enhancements (no change to the main process)：

The body is organized as "core rules first, details sink to references" (progressive disclosure).
The same rule is maintained in only one place, avoid duplication between
```
SKILL.md
```
and
```
references/
```
.
Choose the degree of freedom according to task vulnerability: high freedom (principle), medium freedom (pattern), low freedom (hard constraint).
It is recommended to add a minimum action table (create/modify/refactor/migrate/audit/deprecate) for maintenance tasks to improve execution consistency.
Hybrid skill: Identify the dominant type, organize the body according to the dominant type, and take the content of the secondary type as supplementary paragraphs.

Step 3.5：无损迁移（migrate 场景强制）

Step 3.5: Lossless migration (mandatory for migrate scenarios)

当动作类型为

migrate

或

merge

时，必须执行无损迁移规则：

迁移以“移动/复制 + 引用重组”为主，不以摘要改写替代原文。
原始规则文本（尤其
```
SKILL.md
```
与
```
references/*
```
）必须完整保留。
若需要聚合入口，聚合层仅做路由与导航，不覆盖原规则细节。
迁移后必须可追溯：能从聚合入口定位到原始文本路径。

When the action type is

migrate

merge

, the lossless migration rules must be implemented:

Migration is mainly based on "move/copy + reference reorganization", do not replace the original text with abstract rewriting.
The original rule text (especially
```
SKILL.md
```
and
```
references/*
```
) must be completely retained.
If an aggregation entry is required, the aggregation layer only does routing and navigation, and does not cover the original rule details.
It must be traceable after migration: The original text path can be located from the aggregation entry.

Step 4：自检与验证

Step 4: Self-check and verification

目录名 =
```
name
```
```
description
```
含「做什么」「何时用」和关键词
引用文件仅一层深度，用相对路径
若环境支持：
```
skills-ref validate ./skill-name
```

增强项（不改变主流程）：

无平台绑定术语污染核心规则（Cloud/IDE/产品私有机制）
维护动作可追踪（变更摘要、影响范围、迁移路径）
无冗余文档堆叠（与执行无关的 README/更新日志等）
migrate/merge 场景满足"无损迁移"：原文未被摘要化删改，聚合层仅做导航
类型一致性：正文组织方式与 skill 类型匹配（动作型用 Instructions，约束型用核心原则/行为要求/判断标准/反模式）
约束型 skill 未硬套步骤格式，动作型 skill 未缺少执行流程

Directory name =
```
name
```
```
description
```
contains "what it does", "when to use it" and keywords
Reference files are only one level deep, use relative paths
If the environment supports:
```
skills-ref validate ./skill-name
```

Enhancements (no change to the main process)：

No platform-bound terms pollute core rules (Cloud/IDE/product private mechanisms)
Maintenance actions are traceable (change summary, impact scope, migration path)
No redundant document stacking (README, changelog, etc. unrelated to execution)
migrate/merge scenarios meet "lossless migration": The original text is not deleted or modified by abstraction, and the aggregation layer only does navigation
Type consistency: The body organization method matches the skill type (procedural uses Instructions, declarative uses core principles/behavior requirements/judgment criteria/anti-patterns)
Declarative skills do not force the step format, procedural skills do not lack execution processes

来源与演进路径

Sources and evolution path

来源

Sources

第一层来源：Agent Skills 官方文档（结构、frontmatter、渐进式披露、校验约束）。
第二层来源：社区 skill-creator 文档中的通用方法（内容组织、迭代思路、反模式识别）。

First layer source: Official Agent Skills documentation (structure, frontmatter, progressive disclosure, verification constraints).
Second layer source: General methods in community skill-creator documentation (content organization, iteration ideas, anti-pattern identification).

吸纳策略

Adoption strategy

官方 Step 1–4 作为主流程骨架。
新增内容仅作为“增强项”并入各 Step，不替换主流程。
明确剔除 Cloud/IDE/产品私有绑定内容，保留平台无关规则。

The official Step 1–4 is used as the main process framework.
New content is only incorporated into each Step as "enhancements", and does not replace the main process.
Explicitly remove Cloud/IDE/product private binding content, retain platform-independent rules.

定位与边界

Positioning and boundaries

本 skill 负责规则标准与治理流程，不绑定特定平台。
默认采用静态规则与文档校验，不依赖固定脚本链路。
关注可迁移、可维护、可审计的 skill 设计质量。

This skill is responsible for rule standards and governance processes, and is not bound to a specific platform.
Static rules and document verification are used by default, no fixed script chain is required.
Focus on the design quality of migratable, maintainable and auditable skills.

反模式（必须避免）

Anti-patterns (must be avoided)

将规则绑定到特定 Cloud/IDE/产品私有能力。
把平台安装、打包、发布统计写入规则正文。
在 skill 中堆放与执行无关的辅助文档（如通用 README、更新日志）。
在
```
SKILL.md
```
与
```
references/
```
重复维护同一说明。
用精简摘要替代原始规则正文，导致迁移失真与细节丢失。
将约束型 skill 硬套进 Instructions/Step 1-2-3 格式，导致内容牵强或丢失"始终生效"的语义。
将动作型 skill 写成纯声明式，导致缺少可执行的步骤流程。

Bind rules to specific Cloud/IDE/product private capabilities.
Write platform installation, packaging, release statistics into the rule body.
Pile up auxiliary documents unrelated to execution in the skill (such as general README, changelog).
Maintain the same description repeatedly in
```
SKILL.md
```
and
```
references/
```
.
Replace the original rule body with a concise abstract, resulting in migration distortion and detail loss.
Force declarative skills into the Instructions/Step 1-2-3 format, resulting in far-fetched content or loss of "always effective" semantics.
Write procedural skills as purely declarative, resulting in lack of executable step flow.

参考资料

References

```
references/specification.md
```
- Agent Skills 基础规范与字段约束
```
references/anthropic-enhancements.md
```
- 基于 Anthropic skill-creator 的平台无关增强提炼（含来源与剔除策略）
```
references/skill-type-taxonomy.md
```
- Skill 类型分类学：动作型（procedural）vs 约束型（declarative）的组织方式指导

```
references/specification.md
```
- Agent Skills basic specifications and field constraints
```
references/anthropic-enhancements.md
```
- Platform-independent enhancement extraction based on Anthropic skill-creator (including source and removal strategies)
```
references/skill-type-taxonomy.md
```
- Skill type taxonomy: Guidance on organization methods for procedural vs declarative skills