openydt-skill-maker

openydt-skill-maker — openydt custom Skill maker

CRITICAL: Before starting, you MUST first use the Read tool to read ../openydt-shared/SKILL.md, to master openydt's configuration / profile / signing (v2/v3) / response envelope and status codes / rate limiting / write-operation safety rules. All skills you create must reuse this foundation; do not repeat this content in new skills.

This skill is a meta-skill for "making other openydt skills", benchmarked against Feishu lark-skill-maker: when the user wants to solidify a certain openydt interface (atomic wrapper) or a certain multi-step business process (orchestration) into a reusable Skill, produce a specification-compliant SKILL.md。

When to use this skill

• The user wants to create a new openydt domain skill (such as the "on-site vehicles / monthly passes / blacklist" domain).
• The user wants to package a certain openydt api <cmd> or a certain "fee inquiry → payment" style business chain into a reusable Skill.
• The user wants to normalize an existing SKILL.md (add frontmatter, organize the command table, add to write operations --yes）。

Not part of this skill: actually calling business interfaces (use the corresponding domain skill or openydt api), modifying Go command code (to modify cmd/gen you must first modify the extractor/codegen, not hand-write).

Directory structure

Each skill is a directory under skills/<skill-name>/ , containing at least SKILL.md; when the body is long or there is a large block of reference material, split on-demand content into references/：

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

Naming convention: skill directory names use openydt-<域或场景>(kebab-case), consistent with the frontmatter's name .

frontmatter field descriptions (same specification)

frontmatter must be consistent with existing openydt skills:

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

• description is the key to whether the skill can be correctly recalled; the writing style is benchmarked against Anthropic skill-creator:One sentence of WHAT (this domain's responsibility + read/write boundary) + one sentence of WHEN (typical trigger scenarios), overall condensed to about 100–150 characters, giving 3–6 distinctive representative scenarios is enough,do not pile up synonyms。
  • Why not pile up: spreading out the Cartesian product of "read/write verbs × business nouns" will compete with sibling domains for the same word (e.g., "fee inquiry/payment" was once claimed by 5 skills at the same time), dilute the discriminative signal, bloat the resident token count, and instead reduce recall accuracy. Discriminative power comes fromboundaries, not quantity.
  • Same-name cross-domain scenarios need an added boundary sentence, for example record notes "historical bills/payment records (for real-time fee calculation please use the trade domain)". For specific ownership see "Trigger word de-confliction" below.
  • Whether triggering is accurate should be objectively verified according to this skill's "Production steps" using skill-creator's trigger eval Objective Acceptance, rather than relying on the subjective judgment of "whether there are enough words".
• cliHelp Fill in the domain's real help command, to make it easy for humans to verify whether subcommands exist.

Trigger word de-confliction (each trigger phrase belongs to only one owner domain)

skill-creator's primary deduction item is "trigger word conflict with sibling skills". openydt is a multi-domain skill library under a single platform, and is most prone to collisions. Rules:Each bare trigger phrase belongs to only one owner domain; other domains use qualifiers + write a boundary sentence in the description; for same-name scenarios of read vs write, assign ownership by "primary operation". Before a new skill goes live, it must undergo one round of trigger-word deduplication against the descriptions of existing domains.

Known adjudication table (must be followed; new domains should align accordingly):

Trigger word	owner (exclusive bare word)	How other domains change it
Query fee / calculate fee / pay fee / online payment	billing(trade) real-time fee calculation	record→"query payment records/bill details"; monthticket→"monthly ticket payment/deduction records"; park only "park fee standard query"; coupon does not claim it
Screen display / voice announcement	device (dispatch: push screen display/announcement/broadcast)	park→"query screen display content/what should be displayed"
On-site vehicle	record (details)	data→"real-time on-site count/on-site statistics"
Query bill	record = "payment records/bill details"	data = "bill summary/business report"
E-coupon / coupon	coupon (query/issue/receive closed loop)	park→"vehicle coupon record (read-only)"; monthticket→"park agreement sync scan code"
Special vehicle type / specialCarTypeId / VIP group	monthticket (create/query)	list only "referenced as an input parameter", does not claim "create"
Generic term "query vehicle"	— (generic terms prohibited, split into qualified phrases)	record "query on-site vehicles/entry-exit records", monthticket "query vehicle owner identity/whether VIP", park "query park information"

Main text structure convention

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

1. CRITICAL read shared first: the first sentence of the main text must be a prominent notice, requiring Read before starting ../openydt-shared/SKILL.md, and do not repeat signatures/status codes/security rules in this skill.
2. When to use this skill + intent routing: clearly state what this domain is responsible for, and provide routing such as "for this type of request, use domain X instead" (to avoid skill overreach).
3. Available command table: use a table to list this domain's commands, with columns "Chinese name | command | read/write | key parameters".
   • 命令 The column must writetruly executableof openydt <域> <use>。
   • 读/写 column indicates read or write;all write commands must be marked in both the table and examples with "requires --yes」。
   • 关键参数 mark required fields (using * or "required"), and array/object-type field descriptions must be passed using --body JSON.
4. Business process(only when there is a multi-step chain): describe chains that need to backfill the response from the previous step (such as "query fee → billing estimate" and "create coupon → sell coupon → issue coupon"), emphasizing that fields must be taken from the previous step's response and must not be fabricated. If there is no strong dependency chain, state "each command is an independent query".
5. Example: give 2-4 commands that can be copied and run directly, including at least one read example; if there are write commands,you must first give one --dry-run preview signed request, then give one --yes actual issuancetwo-step sequence, so that "rehearse first, then execute" can be copied directly. Example hygiene (hard constraint): parkCode must use a test parking lot documented in the shared foundation（1ZS7H5PQH9 / PTD2YBBZ), use current/relative time or neutral placeholders for time parameters—do not copy the catalog sampleBody historical values from 2016–2019, otherwise users will hit 904/911 or empty results as soon as they copy it.
6. Error self-healing quick reference table(required): for each domain, provide a three-column table of "symptom | meaning | recovery action (executable next step)" (following the style of [[openydt-flow-park-access]]), and point to [[openydt-shared]]'s ../openydt-shared/references/result-reading-sop.md。
7. Write operation idempotency(if this domain has writes): name the idempotency key for each write command (billCode/thirdBillCode/uniqNo , etc.), restate "retries reuse the first key, 907 = idempotent hit", and point to ../openydt-shared/references/write-idempotency.md; writes without an explicit key require "check before resending".
8. Key points for interpreting results(required): amount units (yuan / time-voucher minutes),status=1 but data empty, 0 records ≠ none—name the relevant fields within the domain, and point to the detailed rules at ../openydt-shared/references/result-reading-sop.md。

why convention: each MUST/NEVER/CRITICAL is paired with a why sentence(e.g., "read shared first—because signatures/status codes are not repeated in this skill, missing it will use the wrong signature version"), to prevent empty hard rules from being rationalized away by strong models.

references/ on-demand loading convention

• The main body of SKILL.md must beshort(resident context, control tokens):keep the main text within 500 lines; split once it exceeds that. Push large, low-frequency content down to references/<topic>.md, and in the main body use relative links to indicate "Read X when you need it".
• Content suitable for references: complete field dictionaries / long enumeration tables (such as the full set of voucher types and vehicle types), complete business processes with more than two steps, and detailed tables from error codes to handling actions.
• Write the trigger conditions clearly in the main body, for example: "Before handling the complete chain of create voucher → sell voucher → issue voucher, first Read references/<topic>.md(example placeholder, not a real file)", so the model loads on demand rather than reading everything by default.

Commands must actually exist

• Each entry in the command table openydt <域> <use> must actually exist, with only two sources; verify by choosing one:
  • Domain first-class commands: based on the real subcommands of cmd/gen/<域>.go (these are generated by codegen), or run openydt <域> --help to verify.
  • catalog interface: based on catalog/catalog.json in included: true 's interfaces[] , each entry containing cmd(business code) / domain / readwrite / params / sampleBody, from which the command name, read/write attribute, and example parameters can be inferred.
• Do not invent command names or parameters.included:false interfaces (marked excludeReason) are out of scope; do not create a skill for them.
• If the target interface does not yet have a domain first-class command, you may use the generic fallback in the skill openydt api <cmd> --body '{...}' call (see the three-layer command model in shared), but still confirm that the cmd exists in the catalog and is callable.

Mark write operations with --yes

• In the catalog readwrite: "write"(or any operation that changes platform state: payment, gate opening, coupon issuance, monthly pass activation, adding/removing from blacklist, setting parking space, etc.) shall always bewrite command。
• For write commands, mark "write (requires --yes)" in the "Read/Write" column of the command table, and actually include --yesin the examples; when necessary, recommend first --dry-run to preview the signed request. This is consistent with the shared security rules and new skills must not weaken it.

Production Steps

1. Determine the domain/scenario and target interface, go to catalog/catalog.json（included:true) or openydt <域> --help to verify the real commands, read/write attributes, required parameters,sampleBody。
2. Create a new skills/openydt-<名>/SKILL.md, and fill it in according to the frontmatter and body skeleton above; enrich the description with Chinese trigger words.
3. Check the authenticity and read/write annotations of the command table item by item: read/write must match the catalog readwrite item by item, write commands marked --yes；read-only domains must not mix in write commands(if there is indeed a "pseudo-write" statistics interface whose platform contract marks write, it must be explicitly stated in the description/body that "this interface contract marks write, and calling it requires --yes").
4. Sink large blocks of content into references/, leaving on-demand loading guidance in the main body.
5. Also check for blind spots: go to the catalog and see whether this domain has interfaces that "have an endpoint,included:false but direction:callable" (common exclusion reasons such as appointment/authorize/certificate/tag are mostly "functionality not first-class" rather than deprecated). Such interfaces have no dedicated command;a sentence should be added in the body: "use openydt api <cmd> to call, see api-explorer for details" as guidance, rather than omitting it.
6. Self-check (objective takes precedence over subjective): whether the commands all really exist, whether the read/write annotations are consistent with the catalog, whether all write operations are marked --yes and the examples include --dry-run, whether the beginning requires reading shared first,whether trigger words are deduplicated against existing domains (refer to the "Trigger Word Conflict Resolution" table). Whether triggering is accurate,objectively accept using route-trigger evaluation: construct positive examples (should recall this domain) and negative examples (sibling-domain scenarios prone to false recall), write them into evals/routing-evals.json, use tools/eval/routing-eval.workflow.mjs(subagent routing evaluation, not nested) to run acceptance, see baseline tools/eval/ROUTING-BASELINE.md; confirm this domain is hit and conflicting domains are not falsely recalled, and only go live after meeting the standard.

Minimal Template

Unified Rendering Specification (all openydt skills aligned)

1. Command table column names are fixed:中文名 | 命令 | 读/写 | 关键参数。
2. For write operations, the Read/Write column is uniformly written as 写（需 --yes）(do not mix "write", "write(--yes)", etc.).
3. Required fields uniformly use the * suffix (do not mix "required", "(required)", etc.).
4. Key parameters uniformly use flag style (--xxx); for arrays/objects note "use --body」。
5. Cross-skill references uniformly use [[openydt-<域>]] wiki-link (do not use bare command names/relative-path prose).
6. Body punctuation is uniformly full-width; write examplesmust include --dry-run preview linethen --yes。
7. CRITICAL header, "When to Use + Intent Routing", "Available Commands Table", "Business Process", "Error Self-Healing Table", "Examples", "Command Ownership [[links]]" in this fixed order.

Pre-ship Checklist (check each item before going live)

• Each entry in the command table openydt <域> <use> verified by --help/catalog verified to actually exist (zero hallucination)
• Read/write annotations consistent with catalog readwrite item by item; write commands marked --yes and examples include --dry-run
• description WHAT+WHEN, about 100-150 characters, de-conflicted with sibling domain triggers (refer to the arbitration table)
• Contains the three blocks: error self-healing table / write idempotency (if there are writes) / result interpretation key points
• Examples use the documented test parkCode + current/relative time (do not copy historical sampleBody)
• Cross-domain references use [[wiki-link]]; callables not first-classed have api fallback pointers
• Each hard rule is paired with why
• Run routing trigger evaluation: positive/negative example datasets in each skill evals/routing-evals.json, runner is tools/eval/routing-eval.workflow.mjs(subagent routing evaluation), baseline see tools/eval/ROUTING-BASELINE.md; confirm this domain's positive examples hit and conflicting domains are not falsely recalled

Copy the entire paragraph below as the new skill's SKILL.md starting point, replace the angle-bracket placeholders, then check item by item:

---
name: openydt-<域>
version: 1.0.0
description: "<一句 WHAT：本域负责 X，含读/写边界>。<一句 WHEN：典型触发场景，3–6 个有区分度的代表说法，勿堆砌同义词；与兄弟域同名场景加一句边界>。"
metadata:
  requires:
    bins: ["openydt"]
  cliHelp: "openydt <域> --help"
---

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

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

## 何时用本技能

<本域负责什么>。意图路由：
- <这类诉求> → 留在本域。
- <那类诉求> → 改用 `openydt <其它域> --help`。

## 可用命令

`<use>` 为命令真实 kebab 名，调用形如 `openydt <域> <use>`。数组/对象型字段用 `--body '<json>'` 传入。

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

> 标 `*` 为必填。

## 业务流程

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

## 示例

1) 读示例：

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

1. Write example (write operations must add --yes, and if necessary first --dry-run）：

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

## workflow（编排）型技能模板（用于跨域 / 多步业务流程）

上面的「最小模板」是**原子 / 域技能**（包装一个域的命令）。当一个**业务结果**需要把多个命令（常跨域）串成固定管道、且步骤间要回填上一步响应字段时，做成 **workflow（编排）型技能**，对标飞书 `lark-workflow-*`。

| | 原子 / 域技能 | workflow 技能 |
| --- | --- | --- |
| 触发 | API/域级意图（「查在场车」） | 业务结果（「出一份车场经营日报」「缴费后对账」） |
| 正文 | 命令表 + 独立查询 | 固定多步管道 + 步骤间数据回填 |
| 组合 | 自包含 | 组合多个域命令 |
| 命名 | `openydt-<域>` | `openydt-workflow-<场景>` |

额外约定：
- 触发写「业务结果」而非「调某接口」，触发词用结果名（经营日报 / 对账 / 催缴），**不与被组合的域技能抢词**。
- 正文用 **ASCII 管道图**画清数据流与回填字段（哪个字段取自上一步响应）。
- 含写的步骤：**先 `--dry-run` 预览、确认后再 `--yes`**；批量写注意限速（见 shared，约 4/s）。
- 仅当「跨域 / 需多步回填 / 需汇总」才独立成 workflow——单域已能在正文写全的闭环不必重复成技能。

管道图示意（放进 workflow 技能的「## 流程」节）：

{parkCode} ─► openydt parking get-park-on-site-car ──► confirm on-site ─► openydt trade get-park-fee ──► get chargeBillNumber / shouldPayValue └─► openydt trade pay-park-fee --dry-run → confirm → --yes (write) └─► openydt parking get-pay-bill ──► reverse-check whether the amount matches