authoring-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring Skills

撰写Agent技能

Use this skill when creating or modifying agent skills in

.agents/skills/

当你在

.agents/skills/

目录下创建或修改Agent技能时，请参考本指南。

When to Create a Skill

何时创建技能

Create a skill when content is:

Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)
Only relevant for specific tasks (not needed every session)
Self-contained enough to load independently

Keep in AGENTS.md instead when:

It's a one-liner rule or guardrail every session needs
It's a general-purpose gotcha any agent could hit

满足以下条件时，请创建独立技能：

内容过于详细，不适合放入AGENTS.md（如代码模板、多步骤工作流、诊断流程）
仅与特定任务相关（不需要在每次会话中加载）
具备足够的独立性，可以单独加载

以下情况请将内容保留在AGENTS.md中：

内容是每次会话都需要的单行规则或约束
内容是所有Agent都可能遇到的通用注意事项

File Structure

文件结构

.agents/skills/
└── my-skill/
    ├── SKILL.md          # Required: frontmatter + content
    ├── workflow.md        # Optional: supplementary detail
    └── examples.md        # Optional: referenced from SKILL.md

.agents/skills/
└── my-skill/
    ├── SKILL.md          # 必填：前置元数据 + 内容
    ├── workflow.md        # 可选：补充细节
    └── examples.md        # 可选：从SKILL.md中引用

Supported Frontmatter Fields

支持的前置元数据字段

yaml

---
name: my-skill # Required. Used for $name references and /name commands.
description: > # Required. How Claude decides to auto-load the skill.
  What this covers and when to use it. Include file names and keywords.
argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
user-invocable: false # Optional. Set false to hide from / menu.
disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
model: opus # Optional. Model override.
context: fork # Optional. Isolated subagent execution.
agent: Explore # Optional. Subagent type (with context: fork).
---

Only use fields from this list. Unknown fields are silently ignored.

yaml

---
name: my-skill # 必填项。用于$name引用和/name命令。
description: > # 必填项。用于Claude判断是否自动加载该技能。
  说明该技能涵盖的内容及适用场景。请包含文件名和关键词。
argument-hint: '<pr-number>' # 可选。提示预期的参数格式。
user-invocable: false # 可选。设置为false可在/菜单中隐藏该技能。
disable-model-invocation: true # 可选。设置为true可阻止自动触发。
allowed-tools: [Bash, Read] # 可选。无需权限即可使用的工具列表。
model: opus # 可选。模型覆盖配置。
context: fork # 可选。启用独立子Agent执行环境。
agent: Explore # 可选。子Agent类型（需配合context: fork使用）。
---

请仅使用本列表中的字段。未知字段将被自动忽略。

Writing Descriptions

撰写技能描述

The

description

is the primary matching surface for auto-activation. Include:

What the skill covers (topic)
When to use it (trigger scenario)
Key file names the skill references (e.g.
```
config-shared.ts
```
)
Keywords a user or agent might mention (e.g. "feature flag", "DCE")

yaml

undefined

description

字段是技能自动激活的核心匹配依据。请包含以下内容：

技能涵盖内容（主题）
适用场景（触发条件）
技能涉及的关键文件名（如
```
config-shared.ts
```
）
用户或Agent可能提及的关键词（如"feature flag"、"DCE"）

yaml

undefined

Too vague - won't auto-trigger reliably

过于模糊——无法可靠触发自动加载

description: Helps with flags.

Good - specific files and concepts for matching

优秀示例——包含具体文件和概念，便于匹配

description: > How to add or modify Next.js experimental feature flags end-to-end. Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.

undefined

description: > 如何端到端地添加或修改Next.js实验性feature flag。适用于编辑config-shared.ts、config-schema.ts、define-env-plugin.ts文件的场景。

undefined

Content Conventions

内容规范

Structure for Action

行动导向的结构

Skills should tell the agent what to do, not just what to know:

Lead with "Use this skill when..."
Include step-by-step procedures
Add code templates ready to adapt
End with verification commands
Cross-reference related skills in a "Related Skills" section

技能内容应指导Agent如何操作，而非仅告知知识：

以“当你需要……时使用本技能”作为开头
包含分步操作流程
提供可直接调整使用的代码模板
结尾附上验证命令
在“相关技能”部分交叉引用关联技能

Relationship to AGENTS.md

与AGENTS.md的关系

AGENTS.md (always loaded)	Skills (on demand)
One-liner guardrails	Step-by-step workflows
"Keep require() behind if/else for DCE"	Full DCE pattern with code examples, verification commands, edge cases
Points to skills via `$name`	Expands on AGENTS.md rules

When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a

$skill-name

reference.

AGENTS.md（始终加载）	技能文件（按需加载）
单行约束规则	分步工作流
"将require()放在if/else语句后以实现DCE"	包含代码示例、验证命令、边缘情况的完整DCE实现方案
通过 `$name` 引用技能	扩展AGENTS.md中的规则

添加新技能时，请在AGENTS.md的对应部分添加一行摘要，并通过

$skill-name

引用该技能。

Naming

命名规则

Short, descriptive, topic-scoped:
```
flags
```
,
```
dce-edge
```
,
```
react-vendoring
```
No repo prefix (already scoped by
```
.agents/skills/
```
)
Hyphens for multi-word names

简短、描述性强、聚焦主题：如
```
flags
```
、
```
dce-edge
```
、
```
react-vendoring
```
无需添加仓库前缀（已通过
```
.agents/skills/
```
目录限定范围）
多词名称使用连字符分隔

Supplementary Files

补充文件

For complex skills, use a hub + detail pattern:

pr-status-triage/
├── SKILL.md         # Overview, quick commands, links to details
├── workflow.md      # Prioritization and patterns
└── local-repro.md   # CI env matching

对于复杂技能，可采用「中心文件+细节文件」的模式：

pr-status-triage/
├── SKILL.md         # 概览、快速命令、详情链接
├── workflow.md      # 优先级判定与模式
└── local-repro.md   # CI环境匹配