Files

T

玉澜andCursor 61b4b56a46 chore(skills): drop dead SAFETY_PREAMBLE_INJECT marker

No injection code ever existed in this repository, so the marker was
inert in all 22 multi SKILL.md files. Remove it and correct the skill
authoring docs to describe safety rules as plain prose.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-04 14:12:46 +08:00

2.8 KiB

Raw Permalink Blame History

Skill Authoring Guide

Contract for the bundled agent skills under skills/. Skills are embedded via skills/embed.go and installed by dws skill setup, so every edit ships with the binary. Keep skill prose concise: long command references belong in references/, not in SKILL.md.

Layout

Path	Role
`skills/mono/`	Single bundled skill (stable mode) with shared `references/` and `scripts/`
`skills/multi/dingtalk-<product>/`	One skill per product (experimental mode)
`skills/multi/dws-shared/`	Shared prerequisite: auth, global flags, routing, safety
`skills/embed.go`	Embeds `mono` + `multi`; do not add new roots

A product skill directory contains:

dingtalk-<product>/
  SKILL.md          # frontmatter + concise routing/usage prose
  references/       # long command references, playbooks
  scripts/          # executable recipes (python), kept minimal

SKILL.md contract

Frontmatter:

---
name: dingtalk-<product>
description: <触发场景>. Use when … Distinct from <相邻skill>(…). 命令前缀：dws <product>。
cli_version: ">=<minimum dws version>"
metadata:
  category: product
  stability: experimental
  requires:
    bins:
      - dws
---

Body rules:

State the safety rules directly in concise prose; there is no injected preamble mechanism in this repository.
State the dws-shared prerequisite for multi skills.
Route by intent: shortcuts table first when one covers the scenario, then scripts/recipes, then atomic commands with dws schema / --help.
Every referenced dws command must exist in the current binary; verify with dws <cmd> --help and keep prose version-agnostic ("以当前 dws 二进制为准").
Mutating commands must point at the leaf Schema confirmation contract; do not invent confirmation rules in prose.

Dual-write rule

Skill behavior described in prose must match the CLI it references. When a command, flag, or confirmation contract changes, update the affected SKILL.md / references/ in the same change; when skill routing changes, check whether Schema selection hints (internal/cli/schema_hints/) need a reviewed update per schema-contributor-guide.md.

Validation

Change	Check
Any skill edit	`make skill-command-integrity`
Referenced CLI surface changed	`./scripts/policy/check-command-surface.sh --strict`
Schema hints touched	`make generate-schema` + schema gates
Recipe scripts	run the script's own smoke path or `test/skill_e2e` when applicable

make skill-command-integrity builds scripts/policy/skill-command-check and verifies every dws command referenced by skills resolves against the current binary. Run it before handoff; do not claim a command exists without it.

2.8 KiB Raw Permalink Blame History