init-vscode

Init VSCode

Initialize or update the project's VSCode configuration files, providing an out-of-the-box set of editor settings and extension recommendations.

Objective

Configure the VSCode development environment for the project, including:

• Extension recommendations (extensions.json)
• Lifecycle governance and rollback-able migration of known extension replacement relationships
• Workspace settings (settings.json)
• Large monorepo performance defaults: three-layer exclusions, search index convergence, TypeScript Server limits, and watching strategy

The configuration uses a smart merge strategy, respecting the user's existing configuration while supplementing best practices. However, this skill has two types ofnarrow-scope strong-policy exceptions：

1. files.eol must converge to "\n"。
2. Registered, well-evidenced extension replacement mappings take precedence over recommendations 's ordinary union merge rule; unknown extensions are never automatically deleted based on guesswork.

Large monorepos must maintain three-layer exclusions in sync:

• files.exclude: Hide dependencies, build artifacts, caches, logs, and sourcemaps from the file tree, reducing Explorer rendering pressure.
• files.watcherExclude: Reduce the VSCode file watcher's scanning of invalid directories, lowering sustained CPU and disk I/O after startup.
• search.exclude: Reduce search and indexing targets, preventing rg, search index, and AI extensions from repeatedly scanning generated files.

Workflow

1. Confirm the target directory

Operate in the project root directory (whether a monorepo or a single project). Ensure the .vscode/ directory exists:

mkdir -p .vscode

2. Handle extensions.json

Read the template configuration (see templates/extensions.json）。

Note: the top of the template file uses // line comments to explain why this file is associated as a workspace jsoncwithin the monorepo, as well as the authoring constraints as JSONC (extensions.json special case). After writing to the target project's .vscode/extensions.json , VS Code parses it normally as JSONC; if the target project also maintains a template copy, it should be explicitly associated as jsonc; do not downgrade it to plain text.

JSONC syntax safety requirements:

• .vscode/extensions.json may retain // line comments and grouping comments, because VS Code parses this file as JSONC.
• The template top note must preferentially use // line comments.
• Do not wrap explanatory text containing /* ... */ block comments containing /* */、*/, code snippets, or comment syntax examples; this will prematurely end the block comment and cause a syntax error.
• Do not delete explanatory comments, grouping comments, or extension-purpose comments just to eliminate parsing errors. The correct goal is 'preserve comments and be syntax-safe'.
• After writing to the target project, .vscode/extensions.jsonmust be validated with a JSONC parser; do not rely only on visual inspection in VS Code.
• When determining the 'active configuration', JSONC-aware parsing capability must be used; it is forbidden to infer active keys using simple regex, line-by-line string search, or by deleting comments and then JSON.parse . Extension IDs, setting keys, tags, and values in comments do not count as active configuration.

If the file does not exist：

• Directly create and write the template content

If the file already exists：

• Read the existing configuration
• If the existing file contains comments, treat it as a JSONC file; do not use JSON.parse as the sole parsing or acceptance method
• Under normal circumstances, merge the recommendations array: after deduplication, keep all extensions (the user's + the template's)
• Under normal circumstances, merge the unwantedRecommendations array: likewise deduplicate
• Before performing a normal array union, you must first check the registered replacement mapping; when there is a match, handle it according to the migration rules in 2.1, and do not let the normal union retain the old extension again
• Keep the other fields in the user configuration (if any)
• When writing back to the file, preserve existing comments and grouping; if the tool being used cannot preserve comments, switch to a minimal text insertion/replacement approach to accomplish the target change, and do not degrade JSONC into comment-free JSON
• Keep the formatting clean (2-space indentation; if comments are preserved, treat it as JSONC)

2.1 Extension replacement relationships and lifecycle governance

The current execution source of truth for the replacement mapping is located at reference/extension-replacement-migrations.md. When extension recommendations in the template are replaced, when the target project has known old extension IDs, old settings namespaces, old commands/keybindings, or when the user reports extension deprecation/activation failures, you must first read that reference, and then perform the normal merge.

At minimum, maintain the following replacement relationships:

Gruntfuggly.todo-tree -> FanaticPythoner.better-todo-tree

When the target project matches a known replacement relationship and the user has not explicitly requested to keep the old recommendation:

1. Remove the old extension ID from recommendations ;
2. Add the new extension ID to recommendations ;
3. Add the old extension ID to unwantedRecommendations ;
4. Keep the user's other unrelated recommendations, unwanted entries, and other fields;
5. Clearly report in the feedback that this is a replacement migration, rather than "adding a new recommendation".

The replacement mapping takes priority over the normal array union, but automatic deletion authority is limited toold IDs that the skill has registered and for which there is sufficient evidence. Unknown extensions, similar extensions, and extensions with similar names must not be automatically deleted based on guesswork.

If the user explicitly requests to continue keeping a certain old extension:

• Respect the user's decision, do not automatically remove it from that project's recommendations , and do not automatically add it to unwantedRecommendations；
• The new extension may still be added, but you must report the "dual recommendation/compatibility risk" and the incomplete migration status;
• The user's explicit decision to keep it must not be interpreted as a "successful migration".

unwantedRecommendations only expresses the workspace's intent of "not wanting to recommend this extension",it is notan uninstall, disable, or runtime isolation mechanism. Writing it must not be treated as evidence that the extension migration is complete.

2.2 Replacement preflight and scope boundaries

For projects that match the replacement mapping, perform a minimal preflight before making changes. When the corresponding capabilities are available, check at least:

• The current VS Code version;
• Whether the old/new extensions are installed and their versions;
• The legacy/current namespace in the workspace settings;
• Keybindings / commands related to the old extension;
• Explicit executable/path overrides, especially paths pointing to VS Code's private internal directories;
• High-risk settings registered in the replacement reference;
• In JSONC, theactive value, rather than comment text;
• whether a rollback baseline exists.

scope must be handled in layers:

1. Workspace .vscode/*: belongs to this skill's normal write set, and can be directly created or merged according to the current user task.
2. VS Code User Settings / User keybindings: belongs to user-level configuration. By default, only detect and report; when modification is needed, you must first clarify the scope, obtain user authorization, create an identifiable backup, and then perform a minimal JSONC-aware migration. Migrate only active old keys, preserve commented-out disabled items, do not format unrelated user settings, and report the backup location and migration namespace at the end.
3. Global extension install/enable/disable/uninstall status: belongs to an independent runtime action. Do not uninstall or disable user extensions just because workspace files were modified; any global state change requires separate authorization and evidence.

Do not hardcode the absolute User Settings path of a particular machine in a skill distributed externally. When user-level migration is needed, locate the real configuration file through the current platform/VS Code environment, and treat the absolute path only as feedback for this execution, not as a long-term skill rule.

2.3 Dedicated migration gate for Todo Tree -> Better Todo Tree

When Gruntfuggly.todo-tree -> FanaticPythoner.better-todo-tree is hit, in addition to the general preflight, check the following risks according to the reference:

• Invalid subTagRegex: BLOCKER, fix the regex before migrating;
• customHighlight: keep a manual visual acceptance WARN; do not claim equivalence based only on static configuration;
• multiline regex: keep a runtime compatibility WARN;
• UTF-16 files: keep a workspace scan WARN;
• explicit ripgrep override: if it points to resources/app/node_modules*、@vscode/ripgrep* and other VS Code private internal layouts, treat it as a high-risk WARN/FAIL, and do not copy that path into a long-term new configuration;
• legacy keybinding / command: verify whether the new extension provides a usable command or compatible alias; when this cannot be statically proven, require manual GUI testing.

Better Todo Tree's long-term configuration should preferentially use the extension's own resolver / packaged ripgrep; do not treat VS Code private internal binary paths as a stable API.

Before replacement, if you need to confirm why these gates exist, read reference/2026-08-16-todo-tree-ripgrep-migration.md. This file is the current executable experience layer and does not depend on development-time reports from the source monorepo.

2.4 Rollback-capable migration principles

• In the first round of replacement, after obtaining user authorization, you may adopt the approach of "install/enable the new extension, disable the old extension but do not uninstall it yet" to retain one acceptance cycle for quick rollback; this is not a permanent dual-install strategy.
• code --list-extensions can only prove "installed", and cannot by itself prove "disabled". Without additional evidence, you can only report installation status and cannot infer enabled status.
• After GUI/runtime acceptance is stable, prompt the user to decide whether to uninstall the old extension; do not uninstall automatically.
• When User Settings migration occurs, the basis for rollback is the pre-migration backup + the reported namespace changes; do not rely on memory to edit in reverse.

2.5 Configuration check

Before merging the template, first check whether the target project's existing .vscode/settings.json contains outdated or inappropriate configuration. Referring to init-ai-md 's migration detection mechanism, classify and mark problematic configurations and prompt the user.

Check item：

1. vue.server.includeLanguages contains "markdown"

   • Reason: this configuration causes the Vue language server to incorrectly process Markdown files, producing adverse effects
   • Mark:[需移除 markdown]
   • Fix: converge the value to ["vue"]

2. files.eol is not "\n"

   • Reason: On Windows, CRLF/LF drift and git phantom modifications are easily produced
   • Markers:[需收敛为 LF]
   • Fix method: overwrite with "\n"

Execution flow：

1. If .vscode/settings.json does not exist, skip this step
2. Read existing configuration
3. Scan the above check items and generate classification markers
4. If any marked items exist, use the AskUserQuestion tool to ask the user whether to fix them
5. After the user confirms the fix, perform the correction first, then proceed to the merge flow in step 3
6. When the user chooses not to fix, keep the original configuration and proceed to the merge flow (but files.eol is still forcibly converged according to the policy keys)

Question example：

检测到以下 VSCode 配置问题：

- vue.server.includeLanguages 包含 "markdown" [需移除 markdown] - 会导致 Vue 语言服务器错误处理 Markdown 文件
- files.eol 为 "auto" [需收敛为 LF] - 建议统一为 "\n" 避免行尾漂移

请选择要修复的项（可多选，用逗号分隔，如：1,2），或输入 0 跳过。

Fix strategy：

• After the user confirms the fix, correct these configurations before merging the template
• Preserve the user's other custom configurations during correction
• The corrected configuration is then processed according to the merge logic in step 3

3. Handle settings.json

Read the template configuration (see templates/settings.json), then:

Large monorepo performance strategy：

• files.exclude、files.watcherExclude、search.exclude must be supplemented synchronously across the same batch of directories; changing only one layer will leave performance gaps in the file tree, watchers, or search index.
• By default, exclude common dependencies, build artifacts, caches, logs, test reports, and sourcemaps, for example node_modules、.git、dist、dist-ssr、build、.next、.nuxt、.output、.vite、.vitepress/dist、.vitepress/cache、.vuepress/dist、.vuepress/cache、.turbo、.vercel、.cache、.temp、.tmp、coverage、.nyc_output、.vitest-reporter-html、.eslintcache、.stylelintcache、*.tsbuildinfo、*.map、logs、*.log。
• search.indexing.maxFileSize converges by default to 1048576, to avoid a 500MB-level setting causing the search index to ingest large files.
• TypeScript by default supplements typescript.tsserver.maxTsServerMemory: 4096、typescript.disableAutomaticTypeAcquisition: true、typescript.tsserver.watchOptions and typescript.tsdk: "node_modules/typescript/lib"。

If the file does not exist：

• Directly create and write the template content

If the file already exists：

• Read existing configuration
• If the existing file contains comments, treat it as a JSONC file and reuse the subsequent Prettier JSONC override rules
• Deep merge objects:
  • For nested objects (such as files.exclude、files.watcherExclude、search.exclude), merge all key-value pairs;explorer.fileNesting.patterns is handled according to the migration rules in 3.4; the old root node and the new root node must not coexist
  • For arrays, deduplicate and merge by default
  • For simple values (strings, booleans, numbers), the default is stillthe user's existing value takes precedence
• But for the following policy keys, the template value must be used to override conflicting values:
  • files.eol: must converge to "\n", and must not retain "\r\n" or "auto"
  • vue.server.includeLanguages: must converge to ["vue"], remove "markdown", to avoid the Vue language server incorrectly handling Markdown files
  • search.indexing.maxFileSize: must converge to 1048576, do not retain a 500MB-level large file index limit
  • typescript.disableAutomaticTypeAcquisition: converges by default to true, to avoid automatically pulling and scanning extra type packages in large repositories
  • typescript.tsserver.watchOptions: must supplement watchFile: "useFsEvents"、watchDirectory: "useFsEvents"、fallbackPolling: "dynamicPriority"
  • typescript.tsdk: by default use the in-project node_modules/typescript/lib
  • typescript.tsserver.maxTsServerMemory: when missing or below 4096 , supplement to 4096; high-risk monorepos can raise it to 8192
  • explorer.fileNesting.patterns: migrate the old CLAUDE.md root node according to 3.4; the old and new root nodes must not coexist, except for the user's explicitly customized AGENTS.md value
• Preserve other fields in the user configuration
• Write back to the file, keeping the JSON/JSONC format neat (2-space indentation)

3.1. files.eol special rules

This skill is specifically responsible for .vscode/settings.json in:

{
	"files.eol": "\n"
}

The handling principles are as follows:

1. If files.eol does not exist: directly add it as "\n"
2. If files.eol already exists but its value is "\r\n"、"auto" or another value: it must be overwritten to "\n"
3. If the user is already "\n": keep unchanged

This is an explicit team policy key, and the default rule of "user simple values take precedence" does not apply.

3.2. Prettier JSONC compatibility rules

This skill implements .vscode/extensions.json by default retains comments, so it is JSONC rather than strict JSON. During execution, you must check the target project's Prettier pipeline to avoid "VS Code can read it, but the formatter reports an error."

Handling steps:

1. Check whether the .vscode/extensions.json、.vscode/settings.json created or updated this time contains // line comments, block comments, or trailing commas.

2. Read the target project's package.json、prettier.config.*、lint-staged.config.*, and determine whether format, lint-staged, or commit hooks will format *.json or all files.

3. If the JSONC file will enter Prettier, then in the target project's prettier.config.mjs append an exact override; this template prohibits trailing commas, so also converge trailingComma: "none"：

   /** @type {import("prettier").Config} */
   const config = {
     overrides: [
       {
         files: ".vscode/extensions.json",
         parser: "jsonc",
         trailingComma: "none",
       },
     ],
   };
   
   export default config;
   

4. If .vscode/settings.json also retains comments, it can be merged with extensions.json into an exact file array:

   {
     files: [".vscode/extensions.json", ".vscode/settings.json"],
     parser: "jsonc",
     trailingComma: "none",
   }
   

5. If there is already overrides, only append missing items or correct the same file's parser / trailingComma, and do not delete existing project configuration such as parser, plugins, printWidth, tabWidth, endOfLine, etc.

6. Do not set all of **/*.json to jsonc。package.json, lockfiles, and configurations read by third-party strict JSON parsers should still remain strict JSON.

7. If the target project has no Prettier configuration, or the formatting command will not cover .vscode/extensions.json, you must also clearly state the judgment result in the feedback, and do not silently skip it.

3.3 Hardening for high-risk projects

When the project is a large pnpm/turbo monorepo, opening VSCode is noticeably slower,Code.exe/rg.exe/tsserver.js continuously occupies CPU, or there are many generated artifacts, harden according to the following strategy:

• You may raise typescript.tsserver.maxTsServerMemory from 4096 to 8192, but do not use it to replace exact tsconfig and exclusion rules.
• Disable or limit AI extensions that index the entire repository, for example by setting Codegeex.RepoIndex to false, or limit the indexing scope in the extension's own configuration.
• .gitignore and VSCode's three-layer exclusion rules need to be maintained in sync; Git ignore only affects version control and will not automatically reduce pressure on the VSCode file tree, watchers, and search index.
• Windows Defender can optionally exclude high-frequency I/O directories such as node_modules、.git、.tmp within the project, reducing the interference of real-time scanning with VSCode startup and search.
• The root tsconfig.json 's include should be precise to the source directories; do not include unrelated directories such as .md、.github、.cursor in the TypeScript scope.
• Skill documents distributed externally should only contain general experience and relative paths, and should not require users to read local diagnostic reports or development-time absolute paths.

3.4. File nesting migration for AI memory files

The template has changed the canonical root node of explorer.fileNesting.patterns to:

{
	"AGENTS.md": "CLAUDE.md,GEMINI.md,DESIGN.md"
}

This is a breaking change that accompanies the init-ai-md single source of truth policy for AGENTS.md When handling existing settings.json :

• If an old template entry "CLAUDE.md": "GEMINI.md,AGENTS.md"exists, remove that entry first, then write the new AGENTS.md entry; do not keep both root nodes side by side.
• Preserve the user's other unrelated explorer.fileNesting.patterns configuration; for AGENTS.md values that the user has explicitly customized, handle them according to the user-priority principle, and state in the feedback that they have not fully converged.

4. Verification results

Verification must distinguish three layers of evidence.Valid configuration + extension installed does not equal successful extension operation.

Layer A: Static configuration

Check whether the two files were correctly created/updated:

ls -la .vscode/

Verify that .vscode/extensions.json itself is valid JSONC:

pnpm exec prettier --parser jsonc --trailing-comma none --check .vscode/extensions.json

If the target project has a Prettier configuration, or format / lint-staged will process JSON files, also verify that the project-level Prettier configuration can correctly take over:

pnpm exec prettier --check .vscode/extensions.json

If .vscode/settings.json retains comments, include it in the narrow-scope check as well:

pnpm exec prettier --parser jsonc --trailing-comma none --check .vscode/settings.json
pnpm exec prettier --check .vscode/settings.json

Static acceptance of the replacement migration must also confirm:

• recommendations / unwantedRecommendations conforms to the mapping;
• the legacy/current settings namespace conforms to the migration plan;
• comment-disabled items were not mistakenly restored as active configuration;
• no stale VS Code private internal binary absolute paths were generated;
• the order of labels/configuration snapshots that need to be preserved after migration is consistent with the active values.

Workspace settings migration must also confirm:

• explorer.fileNesting.patterns has removed the old template root node, and handled the AGENTS.md entry according to the user-priority rule;

If pnpm format will touch a large number of historical files, you can first run the above narrow-scope check, and clearly state in the feedback the reason why full formatting was not run.

Layer B: CLI / Extension Host evidence

When a replacement migration exists, check within the scope allowed by the current environment:

• whether the new extension is actually installed and its version;
• whether the installation/disable policy for the old extension conforms to this rollback plan;
• whether fresh logs contain regression signals such as activation failure,command not found, executable/ripgrep missing, etc.

When there are no fresh Extension Host / runtime logs, you can only mark it as WARN / pending; you must not write "no logs found" as a runtime PASS.

Layer C: GUI / runtime manual acceptance

Whenever the replacement involves UI, commands, or runtime activation, at least require the user or an execution environment with GUI capability to complete the relevant items:

• Reload Window；
• the target view actually appears;
• Refresh/rebuild;
• in-project navigation;
• key operations such as Filter / Group / Expand/Collapse (take applicable items according to extension capabilities);
• highlight/visual difference check;
• fresh restart stability;
• large repository performance (when the task involves performance).

Only when all applicable items of A + B + C are satisfied can you declare "replacement verification passed in the current environment". If only A or A+B can be completed, the feedback must explicitly state "static/CLI passed, GUI runtime acceptance pending".

5. Provide feedback

Report to the user:

• Which files were updated (newly created or merged)
• Approximate change content (how many extension recommendations and how many settings were added)
• If a replacement migration occurs: old/new extension ID, recommendations/unwanted results, settings namespace changes, and rollback status
• If User Settings are touched: authorization scope, backup location, migrated active keys/namespace; user configuration content unrelated to the task must not be disclosed
• If there are conflicts and the user configuration was retained, briefly explain
• JSONC / Prettier override determination result: already completed, reusable configuration already exists, or the current project does not need completion
• Acceptance status for layers A / B / C respectively; if the GUI is not completed, it must be clearly marked pending

Feedback format example：

✅ VSCode 工作区配置已更新

📦 extensions.json: 完成 1 项 replacement migration，并保留其他用户推荐
⚙️ settings.json: 合并工作区配置；User Settings 未修改
🧪 验收: 静态配置 PASS，CLI PASS，GUI runtime acceptance pending

6. Optional plugin configuration

Use the AskUserQuestion tool to ask the user whether they need to add special plugin configuration:

Question content：

是否需要添加以下插件的特殊配置？

1. git-graph - 自定义分支筛选模式（适合团队有特定分支命名规范）
2. cursor - 将 .cursorignore 识别为 ignore 文件类型
3. i18n-ally - 国际化工具配置（自动识别项目中的语言文件路径）

请选择需要配置的插件（可多选，用逗号分隔，如：1,3），或输入 0 跳过。

According to the user's choice, merge the corresponding configuration into settings.json (using the same deep merge logic as step 3).

Optional plugin configuration

git-graph plugin configuration

Purpose: Custom branch filtering modes, suitable for scenarios where the team has specific branch naming conventions.

Configuration example：

{
	"git-graph.customBranchGlobPatterns": [
		{
			"name": "主要分支",
			"glob": "{main,dev}"
		},
		{
			"name": "功能分支",
			"glob": "feat/*"
		},
		{
			"name": "修复分支",
			"glob": "fix/*"
		},
		{
			"name": "发布分支",
			"glob": "release/*"
		}
	]
}

How to customize：

• customBranchGlobPatterns is an array of objects, each object containing name and glob fields
• name: The display name of the branch group, used to identify it in the Git Graph interface
• glob: Branch matching pattern, supports glob syntax (such as *、{}、? , etc.)
• Common team branch patterns:feat/*、fix/*、hotfix/*、release/*
• Can be adjusted according to the team's Git Flow or GitHub Flow conventions
• Supports using curly braces to match multiple branches:{main,dev,master}

cursor file association configuration

Purpose: Recognize the .cursorignore file as an ignore file type, providing syntax highlighting and editing experience.

Configuration description：

{
	"files.associations": {
		".cursorignore": "ignore"
	}
}

This configuration makes VSCode treat the .cursorignore file as the same file type as .gitignore , providing corresponding syntax support.

i18n-ally plugin configuration

Purpose: Internationalization tool configuration, automatically recognizing language file paths in the project.

Template placeholder: Template file templates/plugin-configs/i18n-ally.json uses the {{LOCALES_PATH}} placeholder, which needs to be replaced with the actual path when applying the configuration.

Placeholder replacement logic：

1. Detect i18n paths in the project: Use the Glob tool to search for common internationalization directory patterns:

   // 搜索模式（按优先级排序）
   const patterns = ["**/locales", "**/i18n", "**/lang", "**/locale", "**/translations"];
   

2. Path handling：

   • The found paths need to be converted to paths relative to the project root directory
   • If multiple paths are found, choose the shortest one (usually the topmost level)
   • Exclude paths in directories such as node_modules、dist、.git Path in the directory, etc.

3. Replace placeholders：

   // 伪代码示例
   let localesPath = detectI18nPath(); // 返回如 "src/locales"
   
   if (!localesPath) {
   	// 如果未找到，使用默认值或询问用户
   	localesPath = "src/locales"; // 默认值
   	// 或使用 AskUserQuestion 询问用户
   }
   
   // 替换模板中的占位符
   config["i18n-ally.localesPaths"] = localesPath;
   

4. Handle failure cases：

   • If automatic detection fails, use the default value "src/locales"
   • or use the AskUserQuestion tool to ask the user for the actual i18n path
   • Inform the user in the feedback that the default value was used, and recommend manually checking

Common path patterns：

{
	"i18n-ally.localesPaths": "src/locales"
}

Configuration parameter description：

• localesPaths: Relative path (string) or array of paths to the directory containing the language files
• Paths are relative to the project root directory
• Supports a single path (string) or multiple paths (array)

Complete configuration example：

{
	"i18n-ally.localesPaths": "src/locales",
	"i18n-ally.pathMatcher": "{locale}/{namespace}.{ext}",
	"i18n-ally.keystyle": "nested",
	"i18n-ally.sortKeys": true,
	"i18n-ally.namespace": true,
	"i18n-ally.enabledParsers": ["yaml", "js", "json"],
	"i18n-ally.sourceLanguage": "en",
	"i18n-ally.displayLanguage": "zh-CN",
	"i18n-ally.enabledFrameworks": ["vue"]
}

Implementation steps：

1. Read the template file templates/plugin-configs/i18n-ally.json
2. Use Glob to search for the i18n directory in the project:

   # 搜索常见的 i18n 目录（排除 node_modules 等）
   **/locales
   **/i18n
   **/lang
   

3. Select the first path found (prefer paths under src/ paths under )
4. If no path is found:
   • Use the default value "src/locales"
   • Prompt the user in the feedback: "No i18n directory detected, using the default path 'src/locales', please adjust according to the actual situation"
5. Replace the {{LOCALES_PATH}} placeholder in the template
6. Merge the processed configuration into settings.json

Merge logic details

Array merging

For recommendations、unwantedRecommendations and other array fields, deduplicate and merge by default:

// 伪代码
merged = [...new Set([...userArray, ...templateArray])];

After deduplication, all items are retained.

replacement exception: Before performing the above union, first apply reference/extension-replacement-migrations.md mappings in . The matched old extensions are first removed from recommendations and then the new extensions are added, and the old extensions are added to unwantedRecommendations; except when the user explicitly requests to retain the old extensions. A regular union must not add back old IDs that have already been removed by mapping.

vue.server.includeLanguages Although it is an array, it is a policy key and the default deduplicate-and-merge does not apply; it must converge to ["vue"], and must not contain "markdown"。

Deep object merging

For nested objects (such as files.exclude、files.watcherExclude、search.exclude）：

// 伪代码
merged = {
	...templateObject,
	...userObject, // 用户的键值对优先
};

The user's existing keys remain unchanged, and new keys from the template are added.

Simple value precedence

For explorer.fileNesting.enabled、terminal.integrated.cwd and other simple values:

• If the user already has configuration,fully retain the user's value
• If the user has no configuration, use the template value

Policy key exceptions

The following keys do not follow "user first", but must converge according to the template:

• files.eol → must be "\n"
• vue.server.includeLanguages → must be ["vue"], and must not contain "markdown"
• search.indexing.maxFileSize → must be 1048576
• typescript.disableAutomaticTypeAcquisition → must be true
• typescript.tsserver.watchOptions → must fill in useFsEvents and dynamicPriority
• typescript.tsdk → use by default node_modules/typescript/lib
• typescript.tsserver.maxTsServerMemory → when missing or lower than 4096 , fill it in; high-risk projects can upgrade to 8192

Optional plugin configuration merging

For optional plugin configurations selected by the user to add (git-graph, cursor, i18n-ally):

• Use the same deep merge logic as settings.json
• For git-graph.repository.onLoad.showSpecificBranches and other array fields, deduplicate and merge
• For files.associations and other object fields, merge key-value pairs
• The user's existing configuration always takes precedence and will not be overwritten

Templates and reference content

The template file is located in templates/ directory:

• templates/extensions.json - Extension recommendation list
• templates/settings.json - Workspace settings

The current execution reference is located in reference/：

• reference/README.md - Current reference index and loading boundaries
• reference/extension-replacement-migrations.md - Known extension replacement relationships, scope, preflight/postflight, and rollback rules
• reference/2026-08-16-todo-tree-ripgrep-migration.md - Current migration lessons distilled from the Todo Tree activation failure incident

These templates include commonly used development tool extensions, three-layer exclusion rules, and performance optimization settings, suitable for most frontend projects and large monorepos. reference only stores the current rules that still have execution value for the installed skill, and does not require reading internal monorepo reports from the source.

Notes

• By default, do not delete any of the user'sunrelatedexisting configuration; registered extension replacement mapping is a narrow-scope exception, handling only explicitly mapped old IDs/old namespaces
• Do not modify VS Code User Settings, User keybindings, or global extension installation/enablement/disablement/uninstallation status without explicit authorization
• unwantedRecommendations is not equivalent to uninstalling or disabling an extension
• files.eol is an explicit policy key that must be unified as required by this skill to "\n"
• files.exclude、files.watcherExclude、search.exclude must be kept in sync; when adding or removing performance exclusion items, do not modify only one of the layers
• Do not describe .vscode/extensions.json as plain text; it should preserve JSONC semantics and be compatible with the formatting pipeline through a precise Prettier JSONC override
• Keep JSON / JSONC file formatting clean (2-space indentation, no trailing commas)
• For configuration files that preserve comments, do not use JSON.parse, simple regex, or line-by-line search as the acceptance criteria for the active configuration; use JSONC-aware parser/CST capabilities or an equivalent comment-aware editing approach, and use Prettier --parser jsonc for syntax validation
• Do not generate binary absolute paths that permanently point to VS Code resources/app/node_modules*、@vscode/ripgrep* and other private internal directories
• Static configuration PASS does not equal runtime PASS; when there is no fresh runtime/GUI evidence, pending/WARN must be retained
• If JSONC parsing fails, report the error and suggest that the user manually check the file format
• Externally distributed documentation and reference must not contain development machine absolute paths, source monorepo internal test/report paths, or rules that require reading back from the source to execute

When to use this skill

This skill should be triggered when the user says the following:

• "initialize vscode configuration"
• "configure editor"
• "set up vscode"
• "a new project needs a development environment configured"
• "add vscode recommended extensions"
• "replace/migrate deprecated vscode extensions"
• "extension command not found / activation failed"
• "update workspace settings"
• "team development standards configuration"
• "VSCode starts slowly"
• "large repository opens very slowly"
• "optimize file watching"
• "optimize search indexing"
• "tsserver usage is very high"

Even if the user does not explicitly say "vscode", as long as they mention concepts related to project initialization, development environment setup, editor configuration, etc., this skill should be considered for use.