Skip to content

Release v0.1.0 #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chonghoon merged 1 commit into from
Jun 1, 2026
Merged

Release v0.1.0 #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 182 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,182 @@
# wwst-skills
# SmartThings Developer Skills

> **📢 Notice**
> Features, documentation, and skill behaviors may change. Your feedback via GitHub Issues is highly appreciated!

A collection of AI skills that accelerates SmartThings device integration. It supports the full lifecycle, from initial code generation to WWST certification.

## 📖 Overview

This project provides AI skills for developers who want to integrate devices into the SmartThings ecosystem. Each skill improves development productivity with step-by-step guidance, best practices, code generation, and debugging support.

### SmartThings Device Integration Types

SmartThings supports three integration types depending on the device characteristics and the manufacturer's infrastructure:

| Integration Type | Description | Best For |
|------------------|-------------|----------|
| **Cloud Connected** | A Device Integration in which devices communicate to the SmartThings cloud via your own cloud | Your devices connect to SmartThings through your own cloud backend |
| **Hub Connected** | A Device Integration in which devices connect to SmartThings via a SmartThings hub using Matter, Zigbee, or Z-Wave | Your devices integrate into the ecosystem through a SmartThings Hub |
| **Direct Connected** | A Device Integration in which devices communicate directly to the SmartThings cloud via MQTT / SmartThings SDK | Your IP devices connect to SmartThings without a separate cloud backend |

---

## 🚀 Installation and Usage

### Prerequisites

- SmartThings Developer account ([Sign up](https://developer.smartthings.com/))
- SmartThings CLI (optional, recommended)
- A coding assistant environment such as Claude Code, Codex, or Antigravity

### How To Use These Skills

These skills can be used with AI assistants that support MCP (Model Context Protocol), such as Cline, Cursor, and Claude Desktop.

1. **Installation**
Install the full skill directory under `skills/` that matches your AI development environment.

You can instruct your AI assistant to install the skills directly by pasting the following prompt:

```text
Install Agent Skills from https://github.com/SmartThingsCommunity/wwst-skills.
```

> **💡 Installation Tip**: If your AI Coding Assistant does not support automatic skill installation, refer to the [Open Agent Skills specification](https://agentskills.io/client-implementation/adding-skills-support#step-1-discover-skills) or your AI Coding Assistant's Skills documentation for manual setup instructions.

**Uninstall**
- Delete the copied skill directory, or remove the reference from your tool's configuration.

2. **Invoking a skill**

When you ask in natural language, the AI assistant can automatically activate the appropriate skill:

- **Cloud Connected (With API Spec)**
```text
Help me build a SmartThings Cloud Connected device integration. I have my own REST API specification ready in cloud_spec.md.
```
- **Hub Connected (With Device Spec Details)**
```text
I want to integrate this Zigbee device with SmartThings. It uses a Zigbee endpoint with Basic, Identify, On/Off, Level Control, and Electrical Measurement clusters.
```
- **Direct Connected / MQTT (With Product URL)**
```text
How can I integrate my smart fan into SmartThings using MQTT? It has speed control, oscillation, and a timer. Here is the product description page URL: https://example.com/product
```

---

## 📚 Skill List

This English README currently documents the following skills under `skills/`.

### 1. Cloud Connected (Schema App)

> **Skill**: `smartthings-cloud-connected-developer`

This skill guides developers through the entire lifecycle of creating a SmartThings Cloud Connected (Schema App) integration, from organization setup to code generation, registration, and final WWST certification.

**Key features**
- Step-by-step progression from org setup through certification (5-step workflow)
- Device Profiles and Capabilities mapping
- Schema App code generation
- OAuth configuration, hosting, and Schema App registration guidance
- Debugging support for common integration issues (OAuth, discovery, state sync)

**Best fit**
- Teams with an existing cloud backend who want Cloud Connected integration
- Developers building a Schema App using Node.js
- Teams preparing WWST certification for Cloud Connected devices

### 2. Hub Connected

> **Skill**: `smartthings-hub-connected-developer`

This skill guides WWST certification for hub-connected products that use Zigbee, Matter, or Z-Wave through SmartThings Hub.

**Key features**
- Standard vs Custom path guidance
- Developer Console and Test Suite workflow
- Zigbee Edge driver PR worked example
- Capability mapping and certification guidance

**Best fit**
- Hub-connected products using Zigbee, Matter, or Z-Wave
- Teams preparing WWST certification or driver contribution work

### 3. Direct Connected Device SDK for C

> **Skill**: `smartthings-direct-connected-device-sdk-c-developer`

This skill guides SmartThings Direct Connected integration using the SmartThings Device SDK for C over MQTT.

**Key features**
- IoT core device library vs SDK Reference starting guidance
- Porting boundary and application layer guidance
- Console setup and onboarding asset guidance
- Device identity registration and WWST prerequisites

**Best fit**
- Direct Connected products using the SmartThings Device SDK for C
- Teams working on porting, provisioning, and certification readiness

### 4. Device Onboarding QR Codes

> **Skill**: `smartthings-device-onboarding-qr`

This skill explains SmartThings device onboarding QR requirements across Matter, Zigbee 3.0, Direct Connected, and Mobile Connected products.

**Key features**
- Integration-type-specific QR payload guidance
- Zigbee minimum vs recommended payload coverage
- Direct Connected and Mobile Connected QR field guidance
- Product-oriented payload examples and partner publication notes

**Best fit**
- Teams defining device labels and onboarding assets
- Developers validating QR payload fields before publication
- Partners handling Matter, Zigbee 3.0, Direct Connected, or Mobile Connected onboarding flows

---

## ⚠️ Limitations and Notes

These skills provide development guidance and code generation support for SmartThings device integration. Before applying their output, verify the relevant content with the official SmartThings documentation, Developer Console, SmartThings CLI, and real-device testing.

---

## 🤝 Contributing

If you find a bug, have a suggestion for improvement, or encounter issues while using the skills, please **create an Issue** in this repository. Your feedback is highly appreciated and will help us improve the skills.

---

## 📁 Project Structure

```text
wwst-skills/
├── README.md # README
├── skills/ # Skills
│ ├── smartthings-cloud-connected-developer/
│ ├── smartthings-direct-connected-device-sdk-c-developer/
│ ├── smartthings-device-onboarding-qr/
│ ├── smartthings-hub-connected-developer/
│ └── ...
```

---

## 🔗 Useful Links

### Official Documentation
- [SmartThings Developer Center](https://developer.smartthings.com/)
- [Device Profiles Guide](https://developer.smartthings.com/docs/devices/device-profiles)
- [Capabilities Reference](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference)

### Developer Tools
- [SmartThings CLI](https://github.com/SmartThingsCommunity/smartthings-cli)
- [Schema App SDK (Node.js)](https://github.com/SmartThingsCommunity/st-schema-nodejs)

### Certification and Release
- [WWST Certification Requirements](https://developer.smartthings.com/docs/certification/required-capabilities)
- [Works With SmartThings](https://www.smartthings.com/works-with-smartthings)
96 changes: 96 additions & 0 deletions skills/smartthings-cloud-connected-developer/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
name: smartthings-cloud-connected-developer
description: Guides developers through the entire lifecycle of creating a SmartThings Cloud Connected (ST-Schema) integration, from organization setup to code generation, registration, and final certification. Use whenever the user wants to connect their cloud IoT devices to SmartThings, build a Schema App, or pass Works With SmartThings (WWST) certification.
metadata:
version: "2026-05-29"
---

# SmartThings Cloud Connected Guide

This skill is a prompt and process framework that helps users integrate their cloud devices into the SmartThings ecosystem using the ST-Schema method.

## Core Operating Principles

1. **Adapt to User Language and Context**: Respond in the language the user is using (Korean, English, etc.). Do not re-ask for information already provided in documents or conversation.
2. **Strict Step-by-Step Progression (Human-in-the-Loop)**: From Step 1 through Step 5, **always proceed one step at a time with user confirmation and data provision**. Do not guide through 2 or more steps at once or assume (hallucinate) that steps have been completed.
3. **Hard-Blocking on User Input**: When explicit user information is required—such as OAuth details, data mapping confirmation, or `ST_CLIENT` issued keys—**stop and wait** until the user provides an appropriate response. Never fabricate dummy values or make assumptions to force progression.
4. **Progress Notification**: Clearly inform the user which step is currently in progress and what the next blocker (reason) is.
5. **Modular Guide Review**: Before proceeding with each step, **always read** the corresponding `references/*.md` document using the `view_file` tool and use it as the top-level rule for performing specific tasks.
6. **Verification and Reference Compliance (Anti-Hallucination)**: All technical decisions—Capability IDs, attribute specifications, SDK API specs—must be verified in real-time via CLI (`smartthings-cli`) or official documentation (`browser`) before proposing. Verification results must be reported to and approved by the user.
7. **Work Method Selection Principle (CLI First, User Choice for Console Tasks)**: When performing technical tasks, follow these criteria:
- **When CLI can handle it**: Use `smartthings-cli` as the primary method.
- **Proactive Search**: If `smartthings` fails, try common paths (e.g., `/usr/local/bin`, `C:\Program Files\SmartThings`) or `npm config get prefix` before falling back.
- **When CLI cannot handle it or console (GUI) work is needed**: Do not decide the method arbitrarily; ask the user first. *"Would you like to proceed in the console yourself, or shall I open the browser and we can do it together?"*
- **User chooses to do it themselves (Manual)**: Provide step-by-step text guides for the user to follow.
- **User chooses to work with the agent (Login-Assist Flow)**: The agent opens the console URL in a browser, and once the user confirms login, the agent automates the remaining input/extraction work via `browser_subagent`.

## 👥 Developer Persona and Goals
This skill primarily supports the following users:
- External developers with limited prior knowledge of the SmartThings integration framework
- Developers who want to build Node.js-based projects using Vibe Coding (natural language instruction-driven) methods
- Developers who already have an API server for their own IoT devices but need ST-Schema integration

## 🐛 Specialized Debugging Summary (Quick Reference)
When dealing with complex issues or log analysis, always consult the `references/best-practice-debugging.md` document first for cross-reference. When users report any of the following key issues, provide immediate guidance.

| Symptom | Key Cause and Troubleshooting Guide |
|---------|--------------------------------------|
| Integration item not visible in My Testing Device app | SmartThings mobile app Developer mode is off / Schema not registered in Console. |
| OAuth login screen or popup not appearing | Client ID/Secret typos or missing settings in Console / Redirect URI mismatch on the hosting side. |
| Device list is empty or only loading | Discovery response JSON format does not match Device Profile specification / Check interactionResultHandler logs. |
| External device state updates not reflected | callbackAccessHandler not implemented or Access Token refresh logic missing. |

## 💻 Code Writing Reference (SDK Specification)

When writing or reviewing Schema App code, the following SDK specifications must be strictly followed.

- **Capability ID Prefix (`st.`)**: When using SmartThings standard Capabilities in SDK methods (such as `device.addState`, `response.addDevice`, etc.), the `st.` prefix must always be included.
- **Correct**: `st.switch`, `st.switchLevel`, `st.temperatureMeasurement`
- **Incorrect**: `switch`, `switchLevel`, `temperatureMeasurement`
- **Attribute and Command Names**: Do not add the `st.` prefix to attribute and command names.
- **State Callback Token Mapping**: The Schema App's endpoint receiving events from the partner backend MUST identify which SmartThings user's `accessToken` maps to the incoming `deviceId`. The AI must explicitly guide the user to design a database or mapping logic (e.g., `deviceId` ➔ `partnerUserId` ➔ `ST accessToken`) to correctly route state callbacks.

## 💡 Conversation and Response Scenario Examples
The agent should guide or lead to the next step in the following manner depending on the situation.
- **Initial Start**: "I'd like to integrate a smart plug." → "Welcome! Let's start by checking Step 1 (Organization Setup) for your device integration. Have you ever created an account and organization on the SmartThings Developer Console?"
- **Data Modeling Step (Step 2)**: "Please help me write a thermostat Profile." → "Sure, a thermostat requires Capabilities such as `temperatureMeasurement`, `thermostatMode`, etc. I'll compose the Device Profile JSON with this structure, and you can register it via the SmartThings CLI."
- **Code Auto-Generation Step (Step 3)**: "Please write connector code using /spec/api.json." → "I'll analyze the spec you provided and write a Node.js skeleton code mapping to the SDK's required handlers (discovery, stateRefresh, command). Please review the generated code and let me know whether to proceed to the next step."

## Overall Process (ST-Schema Integration Sequence)

### Step 1: Organization (ORG) and Brand Setup
Set up the Developer Console environment for WWST certification and device registration.
**-> Read the `references/01-org-setup.md` document and guide the user.**

### Step 2: Product and Data Model (Device Profile) Configuration
Select appropriate Device Profiles and Capabilities based on device information, and register the device in the console.
**-> Read the `references/02-device-profile.md` document and guide the user.**

### Step 3: Schema App (ST-Schema) Development
Write the SmartThings Schema server code (Node.js, etc.) that actually controls devices and synchronizes their states.
**-> Read the `references/03-schema-app.md` document and write/guide the code.**

### Step 4: Hosting, App Registration, and Device Callback Setup
Deploy the developed code to a hosting environment (or ngrok), register it in the SmartThings console, and configure OAuth client information.
**-> Read the `references/04-hosting-and-registration.md` document and guide the user.**

### Step 5: Development Testing and Certification
Perform Developer Mode device testing and the official certification process based on CbS/STTS.
**-> Read the `references/05-certification.md` document and guide the user.**

## 🔗 Key Reference Links (Global References)
The agent refers to the following official documentation when verifying concepts or specifications.

| Item | URL |
|------|-----|
| Cloud-Connected Getting Started | https://developer.smartthings.com/docs/devices/cloud-connected/get-started |
| OAuth2 Auth Server | https://developer.smartthings.com/docs/devices/cloud-connected/auth-server |
| Interaction Types | https://developer.smartthings.com/docs/devices/cloud-connected/interaction-types |
| Device Handler Types | https://developer.smartthings.com/docs/devices/cloud-connected/device-handler-types |
| Device Profiles | https://developer.smartthings.com/docs/devices/device-profiles |
| Capabilities Reference | https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference |
| ST-Schema SDK (Node.js) | https://github.com/SmartThingsCommunity/st-schema-nodejs |
| SmartThings CLI | https://github.com/SmartThingsCommunity/smartthings-cli |
| WWST Certification Requirements | https://developer.smartthings.com/docs/certification/required-capabilities |

Now greet the user, ask if they have information about the device they want to integrate, and begin Step 1.
31 changes: 31 additions & 0 deletions skills/smartthings-cloud-connected-developer/references/01-org-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Step 1: Organization (ORG) and Brand Setup Guide

This step sets up the foundational development environment (Developer Console) for integrating with the SmartThings platform.

## Goals
- Establish an **Organization**, which is the entity that will proceed with Works With SmartThings (WWST) certification.
- Set up a **Brand** under which products (devices) will belong.

## Development Guide and Instructions

> **[Console Task Notice]**
> This step is performed through the console GUI. If the user is experiencing difficulties or wants help, first ask *"Shall I open the browser and we can proceed together?"* Only enter the Login-Assist Flow if the user wants it.

1. **Verify/Create Organization**
- Development and WWST certification must be conducted at the Organization level, not under a personal account.
- Ask the user whether they currently have an organization set up.
- If not set up, guide them through the creation process.
- Guide URL: [SmartThings Console - Organization](https://developer.smartthings.com/console/organization)
- Inform the user that they can change the organization they are currently working under via the profile in the upper right corner of the console (`USING CONSOLE AS`).
- If an existing organization exists, inform them that they can request a team invitation (invitation email) from the organization Admin.

2. **Verify/Create Brand**
- Devices must be registered under a specific brand.
- Ask the user whether the brand their product belongs to is registered, and if not, instruct them to create a brand in the console.
- Guide URL: [SmartThings Console - Brands](https://developer.smartthings.com/console/brands)

3. **Requirements Check**
- Remind the user that this step requires their own OAuth2 authentication server. (A mandatory requirement for ST-Schema)
- Authentication server guide: [Auth Server Guide](https://developer.smartthings.com/docs/devices/cloud-connected/auth-server)

Once this step is complete (when the user confirms completion), the agent should inform them that they will proceed to Step 2 (02-device-profile.md) to define the device's detailed specifications.
Loading
Loading