Back to Details

validate-imperative-format

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Validate Imperative Format

验证祈使式格式

This skill validates that every API specification's 
info.description
starts with an imperative action verb. It relies on agent reasoning rather than regex to evaluate whether the opening word is a genuine imperative verb appropriate for describing an API's capabilities.
该 skill 用于验证每个 API 规范中的 
info.description
是否以祈使式动作动词开头。它依靠 Agent 推理而非 regex，来判断开头单词是否是适合描述 API 能力的真正祈使式动词。

When to Use This Skill

何时使用该 Skill

Use this skill when:
  • Reviewing API descriptions for consistent voice and tone
  • Auditing description quality across all specs before a release
  • Fixing descriptions that use boilerplate or passive phrasing
在以下情况下使用该 skill：
  • 审查 API 描述，确保语气和风格一致
  • 发布前审计所有规范中的描述质量
  • 修复使用模板化措辞或被动语态的描述

What Makes a Good API Description

什么是好的 API 描述

A good 
info.description
starts with an imperative verb — a direct command form that tells the reader what the API does. The sentence should read as if completing the phrase "Use this API to..." without actually writing that phrase.
好的 
info.description
应以祈使式动词开头，即使用直接命令形式告诉读者该 API 的功能。整句话应读起来像是补全 “Use this API to...” 这一短语，但不要实际写出该短语。

Examples of good imperative openers

良好的祈使式开头示例

  • Manage APIs, policies, contracts, and SLA tiers.
  • Query audit log events and actions for organizations.
  • Search and describe metric types for the Observability platform.
  • Deploy, configure, and monitor Omni Gateway instances.
  • Tokenize and detokenize sensitive data using configured services.
Common imperative verbs in this context include: Manage, Query, Search, Retrieve, List, Monitor, Track, Deploy, Configure, Create, Export, Publish, Register, Design, Validate, Secure, Transform, among others.
  • Manage APIs, policies, contracts, and SLA tiers.
  • Query audit log events and actions for organizations.
  • Search and describe metric types for the Observability platform.
  • Deploy, configure, and monitor Omni Gateway instances.
  • Tokenize and detokenize sensitive data using configured services.
在此语境中，常见的祈使式动词包括：Manage、Query、Search、Retrieve、List、Monitor、Track、Deploy、Configure、Create、Export、Publish、Register、Design、Validate、Secure、Transform 等。

Forbidden patterns

禁止的模式

Descriptions must not start with any of these boilerplate or passive patterns:
  • Provides programmatic access to...
    — boilerplate filler
  • This is a RAML...
    — format metadata, not a description
  • The X API allows you to...
    — indirect, not imperative
  • This API ...
    — vague, indirect opener
  • API V1...
    — version metadata, not a description
  • A set of endpoints for...
    — passive, not imperative
  • Enables users to...
    — indirect, not imperative
描述不得以下列模板化或被动模式开头：
  • Provides programmatic access to...
    — 模板化填充内容
  • This is a RAML...
    — 格式元数据，而非描述
  • The X API allows you to...
    — 间接表达，并非祈使式
  • This API ...
    — 含糊且间接的开头
  • API V1...
    — 版本元数据，而非描述
  • A set of endpoints for...
    — 被动表达，并非祈使式
  • Enables users to...
    — 间接表达，并非祈使式

Validation Process

验证流程

When asked to validate imperative format, follow these steps:
当被要求验证祈使式格式时，请遵循以下步骤：

Step 1: Discover all API specs

第 1 步：查找所有 API 规范

Find all 
api.yaml
files in the repository root directories (skip 
.claude
, 
scripts
, 
docs
, 
portal
).
在仓库根目录的各级目录中查找所有 
api.yaml
文件（跳过 
.claude
、
scripts
、
docs
、
portal
）。

Step 2: Extract info.description

第 2 步：提取 info.description

For each 
api.yaml
, read the 
info.description
field value.
对于每个 
api.yaml
，读取 
info.description
字段的值。

Step 3: Validate each description

第 3 步：验证每个描述

For each description, evaluate:
  1. Starts with an imperative verb: The first word should be a verb in imperative (command) form. Use your judgment — if the word functions as a direct command that could follow "Use this API to...", it qualifies.
  2. No forbidden patterns: The description must not match any of the boilerplate patterns listed above.
  3. Minimum quality: The description should be at least 20 characters and convey the API's domain and capabilities, not just repeat the title.
对于每个描述，进行以下评估：
  1. 以祈使式动词开头：第一个单词应为祈使式（命令式）动词。请运用判断力——如果该单词用作直接命令，并且能够自然地补全“Use this API to...”，则符合要求。
  2. 不包含禁止模式：描述不得匹配上述任何模板化模式。
  3. 最低质量要求：描述至少应包含 20 个字符，并传达 API 的领域和功能，而不只是重复标题。

Step 4: Report results

第 4 步：报告结果

Produce a summary table:
| API | Status | First Word | Issue |
|-----|--------|------------|-------|
| api-manager | PASS | Manage | - |
| metrics | PASS | Search | - |
| bad-api | FAIL | Provides | Forbidden boilerplate pattern |
| other-api | FAIL | A | Not an imperative verb |
生成摘要表：
| API | 状态 | 首词 | 问题 |
|-----|--------|------------|-------|
| api-manager | PASS | Manage | - |
| metrics | PASS | Search | - |
| bad-api | FAIL | Provides | 禁止的模板化模式 |
| other-api | FAIL | A | 不是祈使式动词 |

Step 5: Suggest fixes

第 5 步：建议修复方案

For each failing description, suggest a rewritten version that:
  • Starts with an imperative verb
  • Concisely describes the API's domain and capabilities
  • Avoids repeating the API title verbatim
对于每个未通过的描述，建议提供一个改写版本，使其：
  • 以祈使式动词开头
  • 简洁地描述 API 的领域和功能
  • 避免逐字重复 API 标题

Examples

示例

PASS:
yaml
info:
  description: Manage APIs, policies, contracts, and SLA tiers within Anypoint Platform.
FAIL — boilerplate opener:
yaml
info:
  description: Provides programmatic access to manage resources within the platform.
Fix: 
Manage platform resources. Supports CRUD operations for...
FAIL — indirect phrasing:
yaml
info:
  description: The Metrics API allows you to search and describe metric types.
Fix: 
Search and describe metric types for the Observability platform.
FAIL — passive, no imperative verb:
yaml
info:
  description: A set of endpoints for managing things.
Fix: 
Manage things across environments and organizations.
通过：
yaml
info:
  description: Manage APIs, policies, contracts, and SLA tiers within Anypoint Platform.
失败 — 模板化开头：
yaml
info:
  description: Provides programmatic access to manage resources within the platform.
修复：
Manage platform resources. Supports CRUD operations for...
失败 — 间接表达：
yaml
info:
  description: The Metrics API allows you to search and describe metric types.
修复：
Search and describe metric types for the Observability platform.
失败 — 被动表达且没有祈使式动词：
yaml
info:
  description: A set of endpoints for managing things.
修复：
Manage things across environments and organizations.