openydt-skill-maker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

openydt-skill-maker — openydt 自定义 Skill 制作器

openydt-skill-maker — openydt Custom Skill Maker

CRITICAL：开始前 MUST 先用 Read 工具读取
../openydt-shared/SKILL.md
，掌握 openydt 的配置 / profile / 签名(v2/v3) / 响应包络与状态码 / 限速 / 写操作安全规则。所有你新建的 skill 都要复用这套基座，不要在新 skill 里重复这些内容。

本技能是「制作其它 openydt skill」的元技能，对标飞书

lark-skill-maker

：当用户想把 openydt 的某个接口（原子封装）或某条多步业务流程（编排）固化成可复用 Skill 时，按本指南产出一个符合规范的

SKILL.md

。

CRITICAL: MUST use the Read tool to read
../openydt-shared/SKILL.md
before starting to master openydt's configuration / profile / signature (v2/v3) / response envelope and status codes / rate limiting / write operation security rules. All newly created Skills must reuse this base; do not repeat this content in new Skills.

This skill is a meta-skill for "creating other openydt Skills", benchmarked against Feishu's

lark-skill-maker

: when users want to solidify a specific openydt interface (atomic encapsulation) or a multi-step business process (orchestration) into a reusable Skill, follow this guide to produce a standardized

SKILL.md

何时用本技能

When to Use This Skill

用户要新建一个 openydt 域技能（如「在场车 / 月票 / 黑名单」域）。
用户要把某个
```
openydt api <cmd>
```
或某条「查费 → 缴费」式业务链路封装成可复用 Skill。
用户要把已有 SKILL.md 规范化（补 frontmatter、整理命令表、给写操作加
```
--yes
```
）。

不属于本技能：实际调用业务接口（用对应域技能或

openydt api

）、改 Go 命令代码（改

cmd/gen

须先改抽取器/codegen，而非手写）。

Users want to create a new openydt domain Skill (e.g., "on-site vehicle / monthly pass / blacklist" domains).
Users want to encapsulate a specific
```
openydt api <cmd>
```
or a business link like "check fee → pay fee" into a reusable Skill.
Users want to standardize an existing SKILL.md (supplement frontmatter, organize command tables, add
```
--yes
```
to write operations).

Not applicable to this skill: actual calling of business interfaces (use corresponding domain Skills or

openydt api

), modifying Go command code (modifying

cmd/gen

requires changing the extractor/codegen first instead of writing manually).

目录结构

Directory Structure

每个 skill 是

skills/<skill-name>/

下的一个目录，至少含

SKILL.md

；正文较长或有大块参考资料时，把按需内容拆到

references/

：

skills/
  openydt-shared/SKILL.md        # 共享基座（所有 skill 都先 Read 它）
  openydt-<域>/
    SKILL.md                     # 主入口：frontmatter + 正文（必须精简，常驻上下文）
    references/                   # 可选：按需加载的大块内容
      <topic>.md                 # 如字段字典、完整枚举表、长业务流程

命名约定：技能目录名用

openydt-<域或场景>

（kebab-case），与 frontmatter 的

name

一致。

Each Skill is a directory under

skills/<skill-name>/

, which must contain at least

SKILL.md

; when the main content is long or there are large chunks of reference materials, split the content into

references/

as needed:

skills/
  openydt-shared/SKILL.md        # Shared base (all Skills must Read it first)
  openydt-<domain>/
    SKILL.md                     # Main entry: frontmatter + main content (must be concise, resident in context)
    references/                   # Optional: large content loaded on demand
      <topic>.md                 # e.g., field dictionary, complete enumeration table, long business process

Naming convention: Use

openydt-<domain or scenario>

(kebab-case) for the Skill directory name, which must match the

name

in frontmatter.

frontmatter 字段说明（同规范）

Frontmatter Field Description (Same as Specification)

frontmatter 必须与现有 openydt 技能一致：

yaml

---
name: openydt-<域>                 # 必填，与目录名一致，kebab-case
version: 1.0.0                      # 必填，语义化版本
description: "<一句话职责>。<触发词富集>。"  # 必填，见下方要求
metadata:
  requires:
    bins: ["openydt"]              # 必填，声明依赖 openydt 二进制
  cliHelp: "openydt <域> --help"   # 建议：让使用者快速看到真实子命令
---

```
description
```
是技能能否被正确召回的关键，必须富含中文触发词：先用一句话说清楚职责（覆盖哪个域、做读还是写），再罗列用户可能的口语说法（如「查车场、空车位、查费、发券、加黑名单、开月票」等同义/近义词），把读写动词和业务名词都铺开。参考
```
openydt-park
```
/
```
openydt-coupon
```
的 description 密度。
```
cliHelp
```
填该域真实的帮助命令，便于人类核对子命令是否存在。

Frontmatter must be consistent with existing openydt Skills:

yaml

---
name: openydt-<domain>                 # Required, same as directory name, kebab-case
version: 1.0.0                      # Required, semantic versioning
description: "<one-sentence responsibility>. <enriched trigger words>."  # Required, see requirements below
metadata:
  requires:
    bins: ["openydt"]              # Required, declare dependency on openydt binary
  cliHelp: "openydt <domain> --help"   # Recommended: allow users to quickly view real subcommands
---

```
description
```
is the key to correct recall of the Skill, must be rich in Chinese trigger words: first use one sentence to clarify the responsibility (which domain it covers, whether it is read or write), then list possible colloquial expressions of users (e.g., "check parking lot, empty parking space, check fee, issue coupon, add to blacklist, activate monthly pass" and other synonyms/near-synonyms), spread out read/write verbs and business nouns. Refer to the description density of
```
openydt-park
```
/
```
openydt-coupon
```
.
Fill in the real help command of the domain for
```
cliHelp
```
to facilitate humans to verify whether subcommands exist.

正文结构约定

Main Content Structure Convention

正文按固定骨架写，从上到下：

CRITICAL 先读 shared：正文第一句必须是醒目提示，要求开始前先 Read
```
../openydt-shared/SKILL.md
```
，不在本技能重复签名/状态码/安全规则。
何时用本技能 + 意图路由：说清楚本域负责什么，并给出「这类诉求请改用 X 域」的路由（避免技能越界）。
可用命令表：用表格列出本域命令，列为「中文名 | 命令 | 读/写 | 关键参数」。
- ```
命令
```
  列写真实可执行的
```
openydt <域> <use>
```
  。
- ```
读/写
```
  列标明读还是写；所有写命令在表内与示例里都要标注「需
  --yes
  」。
- ```
关键参数
```
  标必填项（用
```
*
```
  或「必填」），数组/对象型字段说明须用
```
--body
```
  JSON 传入。
业务流程（仅当有多步链路时）：描述需要回填上一步响应的链路（如「查费 → 计费测算」「建券 → 售券 → 发券」），强调字段必须取自上一步响应、不可臆造。无强依赖链则写明「各命令为独立查询」。
示例：给 2-4 个可直接复制运行的命令，至少包含一个读示例和（若有写命令）一个带
```
--yes
```
的写示例；参数尽量取自 catalog 的
```
sampleBody
```
或共享基座的测试车场。

Write the main content according to the fixed skeleton, from top to bottom:

CRITICAL: Read shared first: The first sentence of the main content must be a prominent reminder requiring users to Read
```
../openydt-shared/SKILL.md
```
before starting, and not repeat signature/status code/security rules in this Skill.
When to use this Skill + Intent Routing: Clarify what this domain is responsible for, and provide routing like "please switch to X domain for such requests" (to avoid Skill overstepping).
Available Command Table: List the domain commands in a table with columns "Chinese Name | Command | Read/Write | Key Parameters".
- The
```
Command
```
  column writes real executable
```
openydt <domain> <use>
```
  .
- The
```
Read/Write
```
  column indicates read or write; all write commands must be marked with "requires
  --yes
  " in the table and examples.
- Mark required items in
```
Key Parameters
```
  (use
```
*
```
  or "required"), and explain that array/object-type fields must be passed in via
```
--body
```
  JSON.
Business Process (only when there are multi-step links): Describe links that require filling in the response of the previous step (e.g., "check fee → fee calculation" "create coupon → sell coupon → issue coupon"), emphasize that fields must be taken from the previous step's response and cannot be fabricated. If there is no strong dependency chain, write "all commands are independent queries".
Examples: Provide 2-4 commands that can be directly copied and run, including at least one read example and (if there are write commands) one write example with
```
--yes
```
; try to take parameters from
```
sampleBody
```
of catalog or test parking lots in the shared base.

references/ 按需加载约定

references/ On-Demand Loading Convention

SKILL.md 主体要短（常驻上下文，控制 token）。把大块、低频内容下沉到
```
references/<topic>.md
```
，并在主体里用相对链接指明「需要 X 时再 Read」。
适合放 references 的内容：完整字段字典 / 长枚举表（如券类型、车辆类型全集）、超过两步的完整业务流程、错误码到处置动作的详表。
在主体里写清触发条件，例如：「处理建券 → 售券 → 发券完整链路前，先 Read
references/coupon-flow.md
」，让模型按需加载而非默认全读。

The main body of SKILL.md must be short (resident in context, control tokens). Sink large, low-frequency content to
```
references/<topic>.md
```
, and use relative links in the main body to indicate "Read when X is needed".
Content suitable for references: complete field dictionary / long enumeration tables (e.g., full set of coupon types, vehicle types), complete business processes with more than two steps, detailed tables of error codes to disposal actions.
Clearly write trigger conditions in the main body, for example: "Before handling the complete link of create coupon → sell coupon → issue coupon, first Read
references/coupon-flow.md
", so that the model loads on demand instead of reading all by default.

命令必须真实存在

Commands Must Exist in Reality

命令表里的每条
```
openydt <域> <use>
```
必须真实存在，来源只有两类，二选一核对：
- 域一等命令：以
```
cmd/gen/<域>.go
```
  的真实子命令为准（这些由 codegen 生成），或运行
```
openydt <域> --help
```
  核对。
- catalog 接口：以
```
catalog/catalog.json
```
  中
```
included: true
```
  的
```
interfaces[]
```
  为准，每条含
```
cmd
```
  (业务编码) /
```
domain
```
  /
```
readwrite
```
  /
```
params
```
  /
```
sampleBody
```
  ，可据此推断命令名、读写属性与示例参数。
不要臆造命令名或参数。
```
included:false
```
的接口（标
```
excludeReason
```
）属于越界范围，不要为它建技能。
若目标接口尚无域一等命令，可在技能里用通用兜底
```
openydt api <cmd> --body '{...}'
```
调用（见 shared 的三层命令模型），但仍要确认该
```
cmd
```
在 catalog 中存在且可调用。

Each
```
openydt <domain> <use>
```
in the command table must exist in reality, and can only come from two categories, choose one to verify:
- First-class domain commands: Based on real subcommands in
```
cmd/gen/<domain>.go
```
  (generated by codegen), or verify by running
```
openydt <domain> --help
```
  .
- Catalog interfaces: Based on
```
interfaces[]
```
  marked
```
included: true
```
  in
```
catalog/catalog.json
```
  , each includes
```
cmd
```
  (business code) /
```
domain
```
  /
```
readwrite
```
  /
```
params
```
  /
```
sampleBody
```
  , which can be used to infer command names, read/write attributes and example parameters.
Do not fabricate command names or parameters. Interfaces marked
```
included:false
```
(with
```
excludeReason
```
) are out of scope, do not create Skills for them.
If the target interface does not have first-class domain commands, you can use the general fallback
```
openydt api <cmd> --body '{...}'
```
to call it in the Skill (see the three-layer command model of shared), but still confirm that the
```
cmd
```
exists in the catalog and is callable.

写操作标 --yes

Mark --yes for Write Operations

catalog 中
```
readwrite: "write"
```
（或任何会改变平台状态的操作：缴费、开闸、发券、开通月票、加/移黑名单、设置车位等）一律为写命令。
写命令在命令表的「读/写」列标「写（需
```
--yes
```
）」，并在示例中实际带上
```
--yes
```
，必要时建议先
```
--dry-run
```
预览签名请求。这条与 shared 的安全规则一致，新技能不得弱化。

Operations marked
```
readwrite: "write"
```
in the catalog (or any operation that changes the platform state: pay fee, open gate, issue coupon, activate monthly pass, add/remove from blacklist, set parking space, etc.) are write commands.
Mark write commands as "Write (requires
```
--yes
```
)" in the "Read/Write" column of the command table, and actually add
```
--yes
```
in examples; it is recommended to preview the signature request with
```
--dry-run
```
first if necessary. This is consistent with the security rules of shared, and new Skills must not weaken this requirement.

制作步骤

Production Steps

确定域/场景与目标接口，去
```
catalog/catalog.json
```
（
```
included:true
```
）或
```
openydt <域> --help
```
核对真实命令、读写属性、必填参数、
```
sampleBody
```
。
新建
```
skills/openydt-<名>/SKILL.md
```
，按上面 frontmatter 与正文骨架填写；description 富集中文触发词。
命令表逐条核对真实性与读写标注，写命令标
```
--yes
```
。
大块内容下沉
```
references/
```
，主体留按需加载指引。
自检：命令是否都真实存在、写操作是否都标
```
--yes
```
、是否在开头要求先读 shared、description 触发词是否充分。

Determine the domain/scenario and target interface, verify real commands, read/write attributes, required parameters, and
```
sampleBody
```
in
```
catalog/catalog.json
```
(
```
included:true
```
) or via
```
openydt <domain> --help
```
.
Create
```
skills/openydt-<name>/SKILL.md
```
, fill in according to the above frontmatter and main content skeleton; enrich Chinese trigger words in description.
Verify the authenticity and read/write marking of each command in the command table, mark
```
--yes
```
for write commands.
Sink large content to
```
references/
```
, leave on-demand loading guidance in the main body.
Self-check: whether all commands exist in reality, whether all write operations are marked with
```
--yes
```
, whether it requires reading shared at the beginning, whether the description has sufficient trigger words.

最小模板

Minimal Template

把下面整段复制为新技能的

SKILL.md

起点，替换尖括号占位后逐项核对：

markdown

---
name: openydt-<域>
version: 1.0.0
description: "<一句话职责：本域负责 X，含读/写>。触发词：<列尽用户可能说的中文同义词，如 查X、看X、新建X、修改X、删除X、X列表、X编码……>。"
metadata:
  requires:
    bins: ["openydt"]
  cliHelp: "openydt <域> --help"
---

Copy the entire following section as the starting point for a new Skill's

SKILL.md

, replace the angle bracket placeholders and verify item by item:

markdown

---
name: openydt-<domain>
version: 1.0.0
description: "<一句话职责：本域负责 X，含读/写>。触发词：<列尽用户可能说的中文同义词，如 查X、看X、新建X、修改X、删除X、X列表、X编码……>。"
metadata:
  requires:
    bins: ["openydt"]
  cliHelp: "openydt <域> --help"
---

openydt-<域> — <中文域名>

CRITICAL：开始前 MUST 先用 Read 工具读取
../openydt-shared/SKILL.md
（认证 / profile / 签名 / 状态码 / 限速 / 安全规则）。未读共享基座不要执行任何命令。

何时用本技能

<本域负责什么>。意图路由：

<这类诉求> → 留在本域。
<那类诉求> → 改用
```
openydt <其它域> --help
```
。

<本域负责什么>。意图路由：

<这类诉求> → 留在本域。
<那类诉求> → 改用
```
openydt <其它域> --help
```
。

可用命令

<use>

为命令真实 kebab 名，调用形如

openydt <域> <use>

。数组/对象型字段用

--body '<json>'

传入。

中文名	命令	读/写	关键参数
<查询某资源>	`openydt <域> <use-read>`	读	`--xxx` *（必填）
<修改某资源>	`openydt <域> <use-write>`	写（需 `--yes` ）	`--xxx` 、 `yyyList` （用 `--body` ）

标
*
为必填。

<use>

为命令真实 kebab 名，调用形如

openydt <域> <use>

。数组/对象型字段用

--body '<json>'

传入。

中文名	命令	读/写	关键参数
<查询某资源>	`openydt <域> <use-read>`	读	`--xxx` *（必填）
<修改某资源>	`openydt <域> <use-write>`	写（需 `--yes` ）	`--xxx` 、 `yyyList` （用 `--body` ）

标
*
为必填。

业务流程

<若有需回填上一步响应的链路，在此描述，强调字段取自上一步响应、不可臆造；否则写「各命令为独立查询，拿到必填参数即可直接调用」。>

示例

读示例：

bash

openydt <域> <use-read> --xxx <值>

写示例（写操作必须加
--yes
，必要时先
```
--dry-run
```
）：

bash

openydt <域> <use-write> --yes --body '{"xxx":"...","yyyList":[{...}]}'

undefined

读示例：

bash

openydt <域> <use-read> --xxx <值>

写示例（写操作必须加
--yes
，必要时先
```
--dry-run
```
）：

bash

openydt <域> <use-write> --yes --body '{"xxx":"...","yyyList":[{...}]}'

undefined