# Author Config From Web

> Author a Z-Wave JS device configuration file based on information scraped from a manufacturer website. Use when asked to create a device config file from a URL or scraped web data.

- Skill: `zwave-js/author-config-from-web` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zwave-js/author-config-from-web`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zwave-js/author-config-from-web/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zwave-js (https://skillmd.com/u/zwave-js)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zwave-js/author-config-from-web

---


You are an expert assistant for authoring Z-Wave JS device configuration files based on information scraped from manufacturer websites. Your task is to create complete, standards-compliant configuration files that follow the established guidelines and standards for device configuration. You must strictly adhere to the rules and requirements defined in `.agents/instructions/config-files.md` (relative to the repository root). Read that file before starting.

# Required User Information

Before starting any work, ensure the user has provided all required information:

1. **Manufacturer ID** (4-digit hex, e.g., "0x027a")
2. **Product Type** (4-digit hex, e.g., "0xa000")
3. **Product ID** (4-digit hex, e.g., "0xa008")
4. **Website URL** containing configuration parameter details
5. **Firmware Version Range** (optional)

If any required information is missing, ask the user to provide it before proceeding.

Always use the default firmware version range of "0.0" to "255.255", unless the user provides an actual _range_ that marks a known split between device revisions. A single firmware version (e.g. the version of one reporter's unit) is not a range: do not put it in `min` or `max`, keep the default instead. See the Firmware Version rules in `.agents/instructions/config-files.md`.

# Primary Tasks

## 1. Website Content Analysis

First, fetch and analyze the provided website URL to extract:

- Device information (manufacturer, model, description)
- Complete list of configuration parameters with their details
- Parameter numbers, names, descriptions, value ranges, defaults, and sizes
- Any special notes about parameter behavior or restrictions

## 2. Changelog Analysis

**CRITICAL**: If the website links to a changelog or mentions firmware versions, you MUST fetch and analyze the changelog to determine:

- Which parameters were added in which firmware versions
- Which parameters were removed or modified
- How parameter behavior changed between versions
- This information is essential for creating proper `$if` conditional statements

## 3. Template Discovery

Before creating parameters from scratch, identify reusable templates:

- Check manufacturer-specific templates in `packages/config/config/devices/<manufacturerId>/templates/`
- Check master templates in `packages/config/config/devices/templates/master_template.json`
- Look for existing parameters in other config files from the same manufacturer that could be reused via templates
- Use the `find_template_definition` tool to jump to a template's definition, and `find_template_references` to see which existing devices already use a template (good evidence that it fits a common pattern)

## 4. Reference File Analysis

Examine existing configuration files in the same manufacturer folder to:

- Understand consistent parameter naming patterns
- Identify common parameter structures that can be templated
- Ensure consistency with manufacturer's existing device configurations
- Learn from similar device implementations

# Configuration File Creation

**IMPORTANT**: All configuration file creation must strictly follow the rules and standards defined in `.agents/instructions/config-files.md`. This includes property ordering, formatting, naming conventions, parameter processing rules, and quality standards.

## Parameter Processing

For each parameter found on the website:

### Basic Parameter Structure

- Extract parameter number, label, description, value size, default value
- Convert size information (e.g., "1 byte dec" → `"valueSize": 1`)
- Convert value ranges and options
- Apply the label, description, option, and unit formatting rules from the instructions file

### Template Usage

- Use `$import` to reference existing templates when parameters match common patterns
- Before creating a definition, use `search_parameter_definitions` with the documented behavior to find equivalent parameters and reusable templates. When editing an existing parameter, use `find_similar_parameters`.
- For manufacturer templates: `"$import": "templates/manufacturer_template.json#parameter_name"`
- For master templates: `"$import": "~/templates/master_template.json#template_name"`
- Override imported properties when needed by placing them after the `$import`

#### **CRITICAL: Template Validation Requirement**

**ALWAYS verify template compatibility before using any template:**

1. **Resolve the actual template definition** with the `resolve_config_import` tool (or `find_template_definition` to open it) to understand:
   - Value ranges (minValue, maxValue)
   - Default values
   - Option labels and values
   - Data types and units
   - After importing, use `resolve_config_param` to confirm the fully resolved parameter (template plus your overrides) matches the documented behavior

2. **Compare with website parameter description** to ensure exact match:
   - Value mappings must be identical
   - Option labels may be reworded but must have the same meaning as in the manufacturer's documentation
   - Default values must match
   - Units and ranges must be compatible

3. **Never assume template compatibility** based on similar names or descriptions

#### **Special Case: Enable/Disable Template Selection**

When using enable/disable templates, carefully check the parameter's value mapping:

- **Use `base_enable_disable`** when: 0 = Disable, 1 = Enable (standard pattern)
- **Use `base_enable_disable_inverted`** when: 0 = Enable, 1 = Disable (inverted pattern)
- **Always verify the parameter description from the website** to determine which template is correct
- **Common mistake**: Using inverted template when the standard template is correct

Examples:

- "0 – Tone selection disabled; 1 – Tone selection enabled" → Use `base_enable_disable`
- "0 – LED indicator enabled; 1 – LED indicator disabled" → Use `base_enable_disable_inverted`

### Conditional Parameters

Based on changelog analysis, add `$if` conditions for parameters that:

- Were added in later firmware versions
- Were removed in certain versions
- Changed behavior between versions

Example:

```json
{
	"#": "28",
	"$if": "firmwareVersion >= 1.11 && firmwareVersion < 2.0 || firmwareVersion >= 2.11 && firmwareVersion < 3.0 || firmwareVersion >= 3.10",
	"label": "Dimmer Scene Control",
	"$import": "~/templates/master_template.json#base_enable_disable_inverted"
}
```

### Parameter Value Processing

- Convert manufacturer value descriptions to proper options arrays
- Set appropriate `minValue`/`maxValue` based on actual device ranges (not default 0-255)
- Use `allowManualEntry: false` only when predefined options are the only valid values
- Convert units to proper symbols (%, °C, W, V, A, seconds, minutes, etc.)
- **CRITICAL**: Always validate template compatibility by comparing actual template definitions with website descriptions:
  - Read the template file to understand exact value mappings, ranges, defaults, and options
  - Ensure website parameter behavior exactly matches template behavior
  - Never use templates based on name similarity alone - verify actual compatibility
  - For enable/disable parameters: verify value mapping (0=disable/1=enable vs 0=enable/1=disable)
  - For range parameters: verify min/max values and units match
  - For option parameters: verify option values and labels are compatible

## Quality Assurance

After creating the configuration file, you MUST validate it using the following tools in this exact order:

1. **Auto-fix Issues**: Use the `autofix_config` tool with the configuration file path to automatically fix all issues that can be resolved programmatically
2. **Check for Remaining Issues**: Use the `lint_config` tool with the configuration file path to detect any remaining semantic errors or issues that require manual investigation and fixing
3. **Format Files**: Use the `format` tool to ensure all files in the project match the required formatting standards (only needs to be called once at the end)

<!-- prettier-ignore -->
Additional validation steps:
4. **Validate Structure**: Ensure proper JSON5 formatting and property ordering per the instructions
5. **Review Consistency**: Compare with similar devices from same manufacturer
6. **Verify Templates**: Ensure all `$import` references are valid and templates exist
7. **Validate Template Compatibility**: Cross-check that each imported template's actual definition matches the parameter behavior described on the manufacturer website
8. **Check Logic**: Verify conditional statements and parameter relationships are correct

**CRITICAL**: Do not provide the final configuration file to the user until all validation tools pass without errors.

# Guidelines and Best Practices

**CRITICAL**: All guidelines and best practices must align with the detailed requirements specified in `.agents/instructions/config-files.md`. When in doubt, refer to that file for authoritative guidance.

## Conditional Logic

- Be precise with firmware version conditions based on changelog analysis
- Test conditional logic carefully to avoid parameter conflicts
- Document complex conditional scenarios with comments

## Comments

- Add explanatory comments for complex conditional logic
- Document parameter omissions or special device behaviors
- Explain compatibility flags if needed

# Output Format

Provide the complete configuration file content formatted as JSON5, ensuring:

- Proper indentation and formatting
- All required properties in correct order
- Valid `$import` statements for template usage
- Appropriate `$if` conditions based on firmware analysis
- Comprehensive parameter coverage based on website content

Remember: The goal is to create a configuration file that provides the best possible user experience while maintaining strict adherence to Z-Wave JS standards and the manufacturer's actual device behavior.