tuyaopen-skill-maker

Files (1)

• SKILL.md

SKILL.md (first lines)

## No `tuyaopen-cli` CLI coverage

This shared skill uses IDE surfaces, Broker capability IDs, and line-neutral platform tooling; direct CLI invocation is not part of this payload.

# TuyaOpen Skill Maker

This skill teaches the catalogue how to grow itself: writing a new
`SKILL.md`, registering it in `skills/index.json`, and passing the local
validators before opening a PR against `tuya/tuyaopen-ide-manifests`. It does
not cover any one skill's subject matter — for that, see the routing table in
skill `tuyaopen-start` (§ *Routing table*).

## Shared capability shortcuts

| Intent | Command |
|---|---|
| List every command's contract (use this to find which group/command your new skill should point at) | `IDE command reference [--group <g>]` |
| One command's flags/mutating/riskLevel | `IDE command reference --group <g> --command <c>` |

Flags aren't listed here — run `IDE command reference --group <g> --command <c>`
for the current set. Resolve `tuyaopen-cli` first per `tuyaopen-start` § 1 (it is
usually not on `PATH`).

## 1. Frontmatter contract

```yaml
---
name: <id>                    # MUST equal the payload directory name (see § 2)
description: >-
  <English description, keywords a retrieval system would match on>
  <Chinese description, same content — retrieval must work in both languages>
license: Apache-2.0
compatibility:
  - <runtime/tool prerequisites, one per line>
---
```

- `name` **must equal** the skill's `id`, which **must equal** the payload
  directory name (`skills/<group>/<id>/`). Since the 2026-08-14 reorg
  all three are mechanically the same string — getting them out of sync is a
  typo away, not a structural necessity, so double-check it.
- `description` carries **both** languages in one field (unlike the
  `index.json` `name`/`summary`/`whenToUse`, which are separate `en`/`zh-CN`
  keys) — include Chinese keywords even in an otherwise-English skill so
  retrieval matches a Chinese-language request too.
- `license` — every existing skill in this catalogue uses `Apache-2.0`;
  match it unless you have a specific reason not to.
- `compatibility` — a plain list of runtime/tool prerequisites (SDK
  activation state, TTY requirement, tool version floors). Optional but every
  existing skill has one.
- Suggested but not required by the validator: `metadata.requires.bins` (a
  list of binaries the skill assumes are on `PATH`) and `metadata.cliHelp`
  (the `--help`/`schema get` invocation an agent should run first) — neither
  is enforced today, but both make an agent's first turn faster.

## 2. id naming rules

- The `id` **is** the payload directory name: `skills/<group>/<id>/SKILL.md`.
  No nesting deeper than that — a sub-skill bundled inside a parent (e.g.
  `tuyaopen-embedded-hardware/references/peripherals/onchip-gpio/`) is fine, but it is not
  separately indexed and does not get its own top-level `<id>` directory.
- **No slashes in the id.** `.claude/skills/` (Claude Code's loader) walks
  exactly one level deep and silently skips anything nested further — a
  slash-bearing id like the pre-reorg `miniapp/ray-common` would install
  invisibly there.
- **Must be `tuyaopen-` prefixed.** This is not cosmetic: the **global**
  install hub (`~/.cursor/skills/`, see skill `tuyaopen-start` § 6) is the
  same directory the community `npx skills` tool (vercel-labs/skills) installs
  into. An unprefixed name (the pre-reorg `smart-panel-dev` is the example on
  record — it became `miniapp-development-workflow` for exactly this reason, with
  `smart-panel-dev` kept as an `aliases` entry) can collide with, and be
  silently overwritten by, an unrelated third-party skill of the same name. The
  prefix is the whole defense.
- The same argument applies **one level down**, to bundled sub-skills, because
  some hosts do not stop at the top level: Codex scans `$HOME/.agents/skills`
  recursively and registers every nested `SKILL.md` as an independent skill, so
  a sub-skill's `name` is a globally visible identifier there too. Hence the
  `tuyaopen/<slug>` namespace form under `references/peripherals/` — measured
  2026-08-17, when `peripheral-sd` was still announcing itself as
  `SD Card Storage`.

## 2a. The three layers, and which one you are writing

Every skill in this catalogue sits on exactly one of three layers. Deciding
which **before** you write is what keeps two skills from describing the same
thing differently — the failure mode this section exists for is real: for
months `iot-product-workflow` and `tuyaopen-cloud` declared the same
three CLI groups and both described creating a product, and nothing said which
one was authoritative.

| Layer | Named | Owns | One-line test |
|---|---|---|---|
| Mechanism | `tuyaopen-start` | CLI identity, the `--json` envelope, exit codes, the risk gate, command and skill self-discovery, the routing table, environment triage | True regardless of what you are building |
| **Phase** | `tuyaopen-workflow-<domain>-dev` | Step order, the state machine, each step's deliverable, **which steps only a human can do**, what is handed to the next phase | Delete it and the agent no longer knows *what to do next* |
| **Capability** | `tuyaopen-<domain>` | Which command groups the domain has, how a single command is invoked, what it requires first, domain concepts and traps, reference data | Delete it and the agent no longer knows *how to execute this step* |

Task skills (`tuyaopen-embedded-build`, `tuyaopen-miniapp-smart-ui`, …) hang
off the capability layer: one job, done one way.

### The two prohibitions that keep phase and capability apart

> **A workflow names commands but never explains them.**
> Write "Step 4 — create the product: follow `tuyaopen-cloud`'s create path".
> Do **not** copy that skill's invocation details, its reference tables, or its
> traps into the workflow.
>
> **A capability skill states preconditions but never order.**
> Write "`sync-schema` requires a bound product". Do **not** write "first bind
> the product, then sync-schema, then build".

The same fact can be phrased either way, which is exactly why the rule needs a
test rather than a feeling:

**Does the sentence still hold if someone arrives at this command out of
order?** If yes it is a precondition and belongs to the capability layer. If it
only holds while walking the sequence, it is order and belongs to the workflow.

### Workflows may name each other — the one exception

From tuya/tuyaopen-ide-manifests, Apache-2.0.

More from tuya/tuyaopen-ide-manifests