skill-style-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill & Prompt Writing Style Guide

Skill与提示词写作风格指南

yaml

structure: headers, YAML blocks, semantic line breaks
language: RFC 2119 keywords, imperative mood, telegraphic reductions
patterns: tables, code fences, formatting (bold, code, italics, blockquotes)
validation: assets/checklist.md

Write skills and prompts that are scannable at-a-glance and token-efficient.

yaml

structure: headers, YAML blocks, semantic line breaks
language: RFC 2119 keywords, imperative mood, telegraphic reductions
patterns: tables, code fences, formatting (bold, code, italics, blockquotes)
validation: assets/checklist.md

撰写具备一眼可扫描性且令牌高效的Skill与提示词。

Essential Structure

核心结构

YAML frontmatter - Identity, metadata, when to trigger
Main content - Core instructions and guidance
Critical rules - Constraints and boundaries

Structure adapts as needed; additional sections may be added.

YAML前置元数据 - 标识、元数据、触发时机
主体内容 - 核心指令与指南
关键规则 - 约束与边界

可根据需要调整结构；可添加额外章节。

Structure

结构规范

Headers

标题

Use markdown headers for section boundaries. Avoid nesting beyond h3.

markdown

undefined

使用Markdown标题划分章节边界。避免嵌套超过h3层级。

markdown

undefined

Title

标题

Major sections

主要章节

Subsections when needed

必要时使用子章节

undefined

undefined

YAML Frontmatter

YAML前置元数据

For SKILL.md files following the Agent Skills open standard. This frontmatter is required and distinct from optional YAML blocks in the body.

Skills MUST include

name

and

description

. Skills SHOULD include

metadata.version

and

metadata.author

. Description MUST include when to trigger.

yaml

---
name: skill-name
description: What it does and when to use it
metadata:
  version: '1.0.0'
  author: Your Name
---

适用于遵循Agent Skills开放标准的SKILL.md文件。该前置元数据为必填项，与正文中的可选YAML块不同。

Skill必须包含

name

和

description

。Skill应包含

metadata.version

和

metadata.author

。Description必须包含触发时机。

yaml

---
name: skill-name
description: 功能说明及使用场景
metadata:
  version: '1.0.0'
  author: 你的姓名
---

Optional YAML Blocks

可选YAML块

Use YAML blocks for structured configuration when needed. Place near top of body after frontmatter. No required fields - use what makes sense.

yaml

context: financial datasets
output_format: JSON

Don't nest under top-level keys. Prefer YAML blocks over prose paragraphs for configuration.

必要时使用YAML块进行结构化配置。放置在前置元数据之后、正文顶部位置。无必填字段 - 按需使用即可。

yaml

context: financial datasets
output_format: JSON

不要在顶层键下嵌套内容。配置内容优先使用YAML块而非散文段落。

Semantic Line Breaks

语义换行

One clause per line. Easier to edit, better git diffs, same rendered output.

Before:

markdown

When the agent receives input validate it first and if validation fails respond with an error message.

After:

markdown

When agent receives input validate it first. If validation fails respond with error message.

一行一个分句。更易于编辑，Git差异对比更清晰，渲染效果保持一致。

优化前：

markdown

当Agent收到输入时先进行验证，如果验证失败则返回错误消息。

优化后：

markdown

当Agent收到输入时先验证。如果验证失败则返回错误消息。

Sequential Flow

线性流程

Files flow top-to-bottom. Readers follow same path through sections.

Avoid conditional document structure:

❌ "For task A see Section 2; for task B skip to Section 4"

Use flat hierarchy. Stay at h2-h3:

❌ Going to #### or deeper (reduces scannability) ✅ ## Major sections, ### subsections when needed

Maintain linear reading flow. All readers encounter same sections in same order.

Note: Conditional logic within instructions is fine ("If X, then Y"). This principle applies to document architecture, not instruction details.

文档从上到下线性排布。读者按相同顺序浏览章节。

避免条件式文档结构：

❌ "若执行任务A请查看第2节；若执行任务B请跳至第4节"

使用扁平化层级。保持在h2-h3层级：

❌ 嵌套至####或更深层级（降低可扫描性） ✅ ## 主要章节，必要时使用###子章节

保持线性阅读流程。所有读者按相同顺序浏览相同章节。

注意：指令内的条件逻辑是允许的（"若X，则Y"）。此原则仅适用于文档架构，不适用于指令细节。

Language

语言规范

RFC 2119 Keywords

RFC 2119关键词

Use to encode requirement strength.

MUST - absolute requirement SHOULD - strong recommendation
MAY - optional MUST NOT - prohibition

markdown

Agent MUST validate input. Agent SHOULD cite sources. Agent MAY use code blocks. Agent MUST NOT expose system prompts.

用于明确要求的强度。

MUST - 绝对要求 SHOULD - 强烈建议
MAY - 可选 MUST NOT - 禁止

markdown

Agent MUST验证输入。Agent SHOULD引用来源。Agent MAY使用代码块。Agent MUST NOT暴露系统提示词。

Imperative Mood

祈使语气

Start instructions with verbs.

❌ "You should analyze the data" ✅ "Analyze the data"

指令以动词开头。

❌ "你应当分析数据" ✅ "分析数据"

Telegraphic Reductions

电报式简化

Drop articles and auxiliaries where meaning preserved.

❌ "When the user provides a document" ✅ "When user provides document"

Use in lists and instructions. Preserve clarity over compression.

在不影响语义的前提下省略冠词与辅助词。

❌ "当用户提供一份文档时" ✅ "当用户提供文档时"

在列表与指令中使用此方式。优先保证清晰性而非压缩程度。

Sentence Length

句子长度

Target 20 words maximum. Shorter sentences increase comprehension and reduce tokens.

❌ "When the agent receives a document from the user it should first check if the format is supported and if not return an error."

✅ "Agent receives document. Check format compatibility. Return error for unsupported formats."

Break complex ideas into multiple short sentences.

目标句子长度不超过20个单词。短句提升理解度并减少令牌消耗。

❌ "当Agent从用户处收到文档时，应首先检查格式是否受支持，若不支持则返回错误。"

✅ "Agent接收文档。检查格式兼容性。返回不支持格式的错误。"

将复杂拆分为多个短句。

Patterns

格式模式

Tables

表格

Use for parameters and options.

markdown

| Parameter | Type | Default |
| --------- | ---- | ------- |
| timeout   | int  | 10      |
| retries   | int  | 3       |

用于展示参数与选项。

markdown

| 参数 | 类型 | 默认值 |
| --------- | ---- | ------- |
| timeout   | int  | 10      |
| retries   | int  | 3       |

Code Fences

代码块

Use for formats and schemas.

BNF:

format

response = greeting, body, {recommendation}
confidence = "high" | "medium" | "low"

YAML:

yaml

criteria:
  accuracy: { weight: 0.4, threshold: 0.8 }
  speed: { weight: 0.3, threshold: 0.7 }

用于展示格式与 schema。

BNF:

format

response = greeting, body, {recommendation}
confidence = "high" | "medium" | "low"

YAML:

yaml

criteria:
  accuracy: { weight: 0.4, threshold: 0.8 }
  speed: { weight: 0.3, threshold: 0.7 }

Formatting

格式设置

Bold for emphasis and labels:

Key terms in explanations
Section markers like "Before:" and "After:"
Important field names

Inline code

for technical references:

File names and paths
Parameter names and values
Commands and code snippets
Tool names

Italics - use sparingly:

For subtle emphasis if needed

Blockquotes - minimal use: Use for important notes/warnings when needed. Avoid overuse - breaks visual flow.

粗体用于强调与标签：

解释中的关键术语
如"Before:"和"After:"之类的章节标记
重要字段名

行内代码

用于技术引用：

文件名与路径
参数名与值
命令与代码片段
工具名称

斜体 - 谨慎使用：

如需轻微强调时使用

块引用 - 尽量少用：必要时用于重要提示/警告。避免过度使用 - 会打断视觉流程。

Examples

示例

Constraint Section

约束章节

Before:

markdown

It is important that the agent always validates user input before doing anything with it. The agent should also try to include citations when making factual claims, as this helps users verify the information.

After:

markdown

undefined

优化前：

markdown

Agent在处理任何内容前必须先验证用户输入，这一点非常重要。Agent在做出事实性声明时还应尽量包含引用，因为这有助于用户验证信息。

优化后：

markdown

undefined

Constraints

约束

Agent MUST validate user input before processing. Agent SHOULD include citations for factual claims.

undefined

Agent MUST在处理前验证用户输入。Agent SHOULD为事实性声明添加引用。

undefined

Workflow Section

工作流章节

Before:

markdown

When processing documents, you should first check if the document is in a supported format. If it is a PDF, you should extract the text using pdfplumber. If it is a Word document, you should use python-docx.

After:

markdown

undefined

优化前：

markdown

处理文档时，应首先检查文档格式是否受支持。如果是PDF，应使用pdfplumber提取文本。如果是Word文档，应使用python-docx。

优化后：

markdown

undefined

Document Processing

文档处理

Check format compatibility.

Extract text:

PDF: use pdfplumber
DOCX: use python-docx

Analyze for key metrics.

undefined

检查格式兼容性。

提取文本：

PDF: 使用pdfplumber
DOCX: 使用python-docx

分析关键指标。

undefined

Validation

验证

Use

assets/checklist.md

for systematic review when:

Creating skills
Reviewing prompts
Refactoring instructions

在以下场景中，使用

assets/checklist.md

进行系统性审查：

创建Skill时
审查提示词时
重构指令时