OpenParable
Skip to content
← Back to skills

Add Setting

Development
add-setting

Add Setting is an Agent Skill for development published in the microsoft/vscode-cmake-tools repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when adding a new cmake.* configuration setting. Touches package.json (contributes.configuration), package.nls.json, src/config.ts (interface + getter), docs/cmake-settings.md, and CHANGELOG.md. Triggers: "add setting", "new setting", "add configuration".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/microsoft/vscode-cmake-tools/blob/HEAD/.github/skills/add-setting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-setting, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Adding a New Configuration Setting

Recipe for adding a new cmake.* setting to CMake Tools.

Files you must touch

FileWhat to add
package.jsonSetting declaration in contributes.configuration.properties
package.nls.jsonEnglish description string
src/config.tsInterface property + EventEmitter + getter
docs/cmake-settings.mdRow in the settings table
CHANGELOG.mdEntry under the current version

Step 1 — Declare the setting in package.json

Add an entry inside contributes.configuration.properties. Key format is cmake.<settingName>.

// package.json  →  contributes.configuration.properties
"cmake.myNewSetting": {
  "type": "boolean",
  "default": false,
  "description": "%cmake-tools.configuration.cmake.myNewSetting.description%",
  "scope": "resource"
}

Rules

  • type — "boolean", "string", "number", "array", "object", or use "oneOf" for union types.
  • default — always required.
  • scope — use "resource" for project-specific settings (most common), "window" for global UI settings, "machine-overridable" for tool paths.
  • description or markdownDescription — must use an NLS key, never a bare string.
  • NLS key format: %cmake-tools.configuration.cmake.<settingName>.description% (wrapped in %).

Real example — cmake.saveBeforeBuild

"cmake.saveBeforeBuild": {
  "type": "boolean",
  "default": true,
  "description": "%cmake-tools.configuration.cmake.saveBeforeBuild.description%",
  "scope": "resource"
}

Step 2 — Add the English string to package.nls.json

Add the NLS key (without the % wrappers) and its English text:

"cmake-tools.configuration.cmake.myNewSetting.description": "Description of what this setting does."

Do not modify any file under i18n/. Translations are handled separately.


Step 3 — Wire up src/config.ts (three changes)

3a — Add property to ExtensionConfigurationSettings

// src/config.ts  →  ExtensionConfigurationSettings interface
export interface ExtensionConfigurationSettings {
    // ... existing properties ...
    myNewSetting: boolean;
}

The type must match what you declared in package.json.

3b — Add EventEmitter to the emitters map

// src/config.ts  →  ConfigurationReader.emitters
private readonly emitters: EmittersOf<ExtensionConfigurationSettings> = {
    // ... existing emitters ...
    myNewSetting: new vscode.EventEmitter<boolean>(),
};

The emitter type parameter must match the interface property type.

3c — Add a getter

Simple pass-through getter (most settings):

get myNewSetting(): boolean {
    return this.configData.myNewSetting;
}

Getter with transformation logic (e.g., sourceDirectory normalizes to array):

get sourceDirectory(): string[] {
    if (!Array.isArray(this.configData.sourceDirectory)) {
        return [this.configData.sourceDirectory];
    }
    return this.configData.sourceDirectory;
}

Step 4 — Document in docs/cmake-settings.md

Add a row to the settings table. Keep alphabetical order.

| `cmake.myNewSetting` | Description of what this setting does. | `false` | no |

Table columns:

ColumnContent
SettingBacktick-quoted cmake.<name>
DescriptionPlain-English description
Default valueBacktick-quoted default
Supports substitutionyes if ${variable} expansion applies, otherwise no

Step 5 — Add a CHANGELOG entry

Add an entry under the current version in CHANGELOG.md, in the Features: or Improvements: section.


Verification checklist

  • package.json — setting declared with correct type, default, scope, and NLS key
  • package.nls.json — English string added
  • src/config.ts — interface property, emitter, and getter all added
  • docs/cmake-settings.md — table row added in alphabetical order
  • CHANGELOG.md — entry added
  • yarn compile succeeds (or npm run compile)
  • No files under i18n/ were modified

See also: .github/copilot-instructions.md for project-wide conventions.