add-config-knob

Adds new configurable settings to a Rust core across struct, JSON, env, CLI, and TUI layers.

10|1|Updated Jul 7, 2026
One-click install
npx skills add https://github.com/catalystctl/catcode --skill add-config-knob-catalystctl
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: add-config-knob
Source: https://github.com/catalystctl/catcode/tree/main/.catalyst-code/skills/add-config-knob
Command: npx skills add https://github.com/catalystctl/catcode --skill add-config-knob-catalystctl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Adding a new runtime-tunable setting to the Catalyst Code core requires touching five separate layers (struct field, JSON parsing, environment variables, CLI flags, and TUI/web surfacing), and missing any one of them produces an inconsistent or silently broken configuration option. ## Core Features & Use Cases - Five-layer wiring guide: Step-by-step instructions for adding a field to the Config struct, reading it from JSON via apply_json, loading CATALYST_CODE_* environment variables, parsing CLI flags, and surfacing it in the TUI/web settings. - Precedence and merge semantics: Documents the full config precedence chain (CLI > env > settings.local.json > settings.json > user config files) and how arrays and objects merge. - Security guardrails: Warns against reading security-sensitive toggles from project-local JSON files and against documenting env vars that are never actually read in load(). - Use Case: You want to add a new timeout knob like request_timeout_secs. Follow the skill to add the struct field with a default, wire JSON/env/CLI parsing, expose it via set_config and the ready event, and verify with cargo clippy and a unit test. ## Quick Start Add a new configuration setting named max_retries to the core following the add-config-knob five-layer wiring steps.

Frequently Asked Questions about add-config-knob

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new config setting to a Rust application?

Add the field to the Config struct with a default, then wire each layer: read it from JSON in apply_json, from an environment variable in load(), and from a CLI flag with a HELP entry. Finally surface it at runtime via set_config and the ready event if the UI needs it.

How to support config from CLI flags, env vars, and JSON files together?

Implement a precedence chain where CLI overrides env, which overrides local and global JSON files. Parse each source in load() and apply_json, using parse with unwrap_or(default) so malformed values never panic.

Why is my environment variable not affecting the application config?

The env var is likely documented but never actually read in the load() function. Every CATALYST_CODE_* variable must have an explicit std::env::var read in load() or it is dead configuration.

Should security-sensitive settings be read from project config files?

No. Security-sensitive toggles like trust_project_plugins must stay env/CLI-only, because an untrusted repository could ship a settings.json that self-enables the toggle and compromises the user.

How do I expose a new config value to a TUI or web frontend?

Add a set_config match arm in main.rs that coerces the incoming value, emit a config_changed event, and include the field in the ready event. Then add it to the TUI settings store and modal or the web reducer and types.