玉澜andCursor
61b4b56a46
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>
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
dingtalk-<product>/
|
|
SKILL.md # frontmatter + concise routing/usage prose
|
|
references/ # long command references, playbooks
|
|
scripts/ # executable recipes (python), kept minimal
|
|
```
|
|
|
|
## SKILL.md contract
|
|
|
|
Frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
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`](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.
|