Duanzhoutao/vscode-skill

VS Code

VS Code 계열 IDE(VS Code, VS Code Insiders, Cursor, VSCodium, Trae, Qoder, CodeBuddy)를 제품 CLI와 구조화된 JSON 설정 파일을 통해 구성하고 운영하기 위한 휴대용 스킬입니다. 기본값은 표준 위치만 사용하며, 명시적 경로는 환경 변수와 설정 파일에서 가져오므로 어떤 머신에서든 수정 없이 실행할 수 있습니다.

플랫폼 참고: 크로스 플랫폼 - Python 게이트웨이 scripts/vscode_skill.py를 통해 지원됩니다. Windows에서는 PowerShell 드라이버 vscode-cli.ps1(원본 구현, 11/11 테스트 통과)로 전달됩니다. macOS 및 Linux에서는 info, ext list, settings path/get/set/smoke, python set-interpreter를 Python에서 기본 구현하며, 나머지는 로컬 code 바이너리로 위임합니다.

빠른 시작

크로스 플랫폼 (권장)

# 감지된 제품, CLI 경로 및 주요 위치 표시
python scripts/vscode_skill.py info

# 설치된 확장 목록 보기
python scripts/vscode_skill.py ext list

# 사용자 settings.json 경로 및 현재 핵심 설정 보기
python scripts/vscode_skill.py settings path
python scripts/vscode_skill.py settings get

# 사용자 설정의 글꼴 크기 변경 (--Apply 로만 실제 기록)
python scripts/vscode_skill.py settings set \
    --FontSize 16 --FontFamily "JetBrains Mono, Consolas, monospace" --Apply

# 프로젝트 범위 설정
python scripts/vscode_skill.py settings set \
    --Scope project --ProjectPath /path/to/project \
    --FormatOnSave true --Apply

# 프로젝트의 Python 인터프리터 설정
python scripts/vscode_skill.py python set-interpreter \
    --ProjectPath /path/to/project --VenvName .venv

Windows 전용 (PowerShell)

PowerShell을 선호하는 경우 동일한 명령을 vscode-cli.ps1을 통해 직접 사용할 수 있습니다:

pwsh -File $PSScriptRoot\scripts\vscode-cli.ps1 info
pwsh -File $PSScriptRoot\scripts\vscode-cli.ps1 ssh open `
    --HostName devbox --LinuxPath /home/user/project

--Product 값:

• auto (기본값): VS Code를 먼저 확인한 후 VS Code Insiders를 확인합니다.
• vscode: code / code.cmd를 사용합니다.
• vscode-insiders: code-insiders / code-insiders.cmd를 사용합니다.
• 설정된 다른 제품 슬러그 (예: cursor, vscodium, trae-cn, qoder, codebuddy-cn): 설정 파일에서 products.<slug>.cliPath, userDataPath, extensionsPath를 사용합니다.

VSCODE_SKILL_PRODUCT 환경 변수를 설정하거나 설정 파일을 통해 기본 제품을 명시적으로 설정할 수 있습니다 (설정 참조).

VS Code 호환 제품

VS Code 및 VS Code Insiders에 대한 내장 자동 감지가 가장 강력합니다. Cursor, VSCodium, Trae, Qoder, CodeBuddy의 경우, 해당 CLI가 환경별 래퍼를 통해 이미 검색 가능하지 않다면 일반 제품 설정 경로를 통해 처리됩니다.

이 스킬은 파생 제품에 대해 VS Code 호환 설정 표면만을 지원합니다:

• 사용자 및 프로젝트 설정 (.vscode/settings.json 포함).
• 프로젝트 .vscode/tasks.json, .vscode/launch.json, .vscode/extensions.json.
• 키바인딩, 스니펫, 프로필, 확장, 템플릿, Python 인터프리터 선택, 그리고 로컬 제품 CLI가 지원하는 원격 스타일 열기 흐름.

이 스킬을 독점 AI 채팅, 계정, 모델 설정, 에이전트 스토어, 제품별 마켓플레이스, 숨겨진 SQLite 상태, 토큰 또는 내부 런타임 파일에 대한 지원으로 사용하지 마십시오. 특히 Qoder와 CodeBuddy의 경우, 사용자가 공식 제품별 문서를 제공하고 별도 어댑터를 요청하지 않는 한 VS Code 호환 편집기/설정 계층으로 지원을 제한하십시오.

설정

경로 및 머신별 기본 설정은 다음 순서로 해석됩니다:

1. 환경 변수 (최우선 순위).
2. 설정 파일 ($VSCODE_SKILL_CONFIG가 설정된 경우 해당 경로, 그렇지 않으면 플랫폼 기본값):
   • Windows: %APPDATA%\vscode-skill\config.json
   • macOS / Linux: $XDG_CONFIG_HOME/vscode-skill/config.json 또는 ~/.config/vscode-skill/config.json
3. 내장 기본값 (최하위 순위).

환경 변수

변수	목적	기본값
VSCODE_SKILL_HOME	스킬 설치 위치	실행 중인 스크립트의 상위 디렉토리
VSCODE_SKILL_CONFIG	설정 파일 경로 재정의	위 플랫폼 기본값
VSCODE_SKILL_TEMP	테스트용 임시 디렉토리 재정의	$TEMP/vscode-skill
VSCODE_SKILL_PRODUCT	기본 --Product 값	auto
VSCODE_CODE_CLI	VS Code CLI의 명시적 경로	자동 감지
VSCODE_INSIDERS_CLI	VS Code Insiders CLI의 명시적 경로	자동 감지
VSCODE_EXTENSIONS_DIR	모든 제품의 확장 설치 디렉토리 재정의	제품 기본값 또는 설정
VSCODE_USER_DATA	사용자 데이터 디렉토리 재정의 (드물게 사용)	플랫폼 기본값

설정 파일 스키마

스킬 루트의 config.example.json을 설정 위치로 복사하고 편집합니다. 모든 키는 선택 사항입니다.

{
  "product": "auto",
  "tempDir": null,
  "products": {
    "vscode": {
      "cliPath": "C:\\Users\\you\\scoop\\apps\\vscode\\current\\bin\\code.cmd"
    },
    "vscode-insiders": {
      "cliPath": "C:\\Users\\you\\scoop\\apps\\vscode-insiders\\current\\bin\\code-insiders.cmd"
    },
    "cursor": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\cursor\\resources\\app\\bin\\cursor.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\Cursor\\User",
      "extensionsPath": "C:\\Users\\you\\.cursor\\extensions"
    },
    "vscodium": {
      "cliPath": "C:\\Users\\you\\scoop\\apps\\vscodium\\current\\bin\\codium.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\VSCodium\\User",
      "extensionsPath": "C:\\Users\\you\\.vscode-oss\\extensions"
    },
    "trae-cn": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\Trae CN\\bin\\trae-cn.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\Trae CN\\User",
      "extensionsPath": "C:\\Users\\you\\.trae-cn\\extensions"
    },
    "qoder": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\Qoder\\bin\\qoder.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\Qoder\\User",
      "extensionsPath": "C:\\Users\\you\\.qoder\\extensions"
    },
    "codebuddy-cn": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\CodeBuddy CN\\bin\\codebuddy.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\CodeBuddy CN\\User",
      "extensionsPath": "C:\\Users\\you\\.codebuddycn\\extensions"
    }
  },
  "ssh": {
    "defaultHost": "localhost",
    "defaultUser": "you"
  },
  "wsl": {
    "defaultDistro": "Ubuntu-24.04"
  }
}

pwsh -File scripts/init-config.ps1을 실행하여 기본 위치에 시작 설정 파일을 작성합니다.

범위 규율

IDE 상태를 기록하기 전에 다음 세 가지 범위로 분류하고 모호한 경우 사용자에게 확인을 받으십시오:

• 읽기 전용 검사: info, ext list/locate, settings get/path. 항상 안전합니다.
• 프로젝트 설정: .vscode\settings.json, tasks.json, launch.json, extensions.json, 프로젝트 스니펫. 커밋할 가치가 있음; 개인 테마, 글꼴, 계정 정보 또는 머신 로컬 절대 경로를 포함하지 마십시오.
• 사용자 / 전역 설정: 사용자 settings.json, keybindings.json, 사용자 스니펫, 프로필 설정, 설치된 확장. 적용하기 전에 항상 대상 제품, 파일, 키, 이전 값(읽을 수 있는 경우), 새 값 및 롤백 경로를 명시하십시오.

규칙:

• settings set은 명시적 --Apply가 필요합니다. 없으면 명령은 입력만 검증합니다.
• ext install은 제품 CLI의 --install-extension을 호출합니다. 갤러리가 실패하면 스크립트는 Open VSX로 자동 재시도하지 않습니다. 명확한 경고를 출력하고 호출자가 결정합니다.
• 이 스킬을 통해 작성된 프로젝트 설정에는 해당 특정 머신에서 재현 가능한 프로젝트가 아닌 이상 머신 로컬 venv를 가리키는 python.defaultInterpreterPath를 포함해서는 안 됩니다.

설정 참조

일반적인 사용자 설정 경로:

• VS Code: %APPDATA%\Code\User\settings.json
• VS Code Insiders: %APPDATA%\Code - Insiders\User\settings.json

일반 키 (settings set으로 모두 설정 가능):

키	플래그	유형
editor.fontFamily	--FontFamily	문자열
editor.fontSize	--FontSize	정수
editor.lineHeight	--LineHeight	숫자
workbench.colorTheme	--ColorTheme	문자열
workbench.iconTheme	--IconTheme	문자열
workbench.productIconTheme	--ProductIconTheme	문자열
editor.wordWrap	--WordWrap	문자열
editor.tabSize	--TabSize	정수
editor.formatOnSave	--FormatOnSave	불리언
files.autoSave	--AutoSave	문자열
editor.minimap.enabled	--Minimap	불리언
python.defaultInterpreterPath	(python set-interpreter로 설정)	문자열

임의의 키의 경우 --SettingKey <key> --SettingValue <value>를 전달합니다. 값은 변환됩니다: true/false → 불리언, 정수/실수 → 숫자, {...} / [...] → JSON, 그 외는 문자열.

JSON 파일은 VS Code의 JSON-with-Comments 스타일을 사용할 수 있습니다. 스크립트의 표준 JSON 파서는 순수 JSON만 처리합니다. 주석이 포함된 파일은 편집기나 JSONC 인식 도구를 통해 편집해야 합니다.

명령

pwsh -File scripts/vscode-cli.ps1 info
pwsh -File scripts/vscode-cli.ps1 ext list
pwsh -File scripts/vscode-cli.ps1 ext locate --Id ms-python.python
pwsh -File scripts/vscode-cli.ps1 ext install --Id ms-python.python
pwsh -File scripts/vscode-cli.ps1 ext install --Path D:\downloads\some-extension.vsix

pwsh -File scripts/vscode-cli.ps1 settings path
pwsh -File scripts/vscode-cli.ps1 settings get
pwsh -File scripts/vscode-cli.ps1 settings set --FontSize 16 --Apply
pwsh -File scripts/vscode-cli.ps1 settings set --Scope project --ProjectPath D:\projects\demo --FormatOnSave true --Apply
pwsh -File scripts/vscode-cli.ps1 settings smoke

pwsh -File scripts/vscode-cli.ps1 python make-venvs --ProjectPath D:\projects\demo
pwsh -File scripts/vscode-cli.ps1 python set-interpreter --ProjectPath D:\projects\demo --VenvName .venv
pwsh -File scripts/vscode-cli.ps1 python verify --ProjectPath D:\projects\demo --ExpectedVenvName .venv

pwsh -File scripts/vscode-cli.ps1 ssh smoke --HostName localhost
pwsh -File scripts/vscode-cli.ps1 ssh open --HostName devbox --LinuxPath /home/user/project
pwsh -File scripts/vscode-cli.ps1 wsl list
pwsh -File scripts/vscode-cli.ps1 wsl open --Distro Ubuntu-24.04 --LinuxPath /home/user/project

CLI 해석 순서: 명시적 환경 변수 (VSCODE_CODE_CLI / VSCODE_INSIDERS_CLI) → config.products.<product>.cliPath → Get-Command code.cmd (PATH) → Get-Command code (PATH) → %LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd (Windows 기본값). 일반 제품은 products.<product>.cliPath가 없으면 명확하게 실패하며, VS Code로 자동 매핑되지 않습니다.

템플릿 및 번들 콘텐츠

스킬은 references/ 아래에 선별된 콘텐츠를 제공합니다:

• settings-index.md — 유형, 기본값, 범위와 함께 가장 많이 사용되는 80개 설정.
• settings-precedence.md — 11단계 우선 순위 모델 + 다중 루트 작업 영역 동작.
• tasks-templates.md + templates/tasks/*.json — Node, TypeScript, Python, Go, Rust, Docker, Make를 위한 10개의 즉시 사용 가능한 tasks.json.
• launch-templates.md + templates/launch/*.json — 동일한 언어 및 Chrome을 위한 9개의 즉시 사용 가능한 launch.json.
• extension-packs.md — 8개의 선별된 스택 (frontend-web, backend-python, backend-node, data-science, systems, devops, polyglot-baseline, ai-coding).
• keybindings-cheatsheet.md — 가장 많이 다시 매핑된 50개의 단축키.

# 사용 가능한 tasks 템플릿 목록 보기
python scripts/vscode_skill.py tasks list

# 템플릿에서 .vscode/tasks.json 생성 (--Force 없으면 덮어쓰지 않음)
python scripts/vscode_skill.py tasks init --Template python-pytest --ProjectPath /path/to/project --Apply

# launch 템플릿도 동일한 방식
python scripts/vscode_skill.py launch init --Template python-current-file --ProjectPath /path/to/project --Apply

# 선별된 확장 스택
python scripts/vscode_skill.py extensions stacks
python scripts/vscode_skill.py extensions recommend --Stack frontend-web
python scripts/vscode_skill.py extensions install --Stack backend-python
python scripts/vscode_skill.py extensions pin --Stack polyglot-baseline --ProjectPath /path/to/project

프로필, 설정 동기화, 다중 루트 작업 영역

# 프로필 검사 (읽기 전용)
python scripts/vscode_skill.py profile list
python scripts/vscode_skill.py profile show --Profile <name>

# 설정 동기화 저장소가 로컬에 있는지 확인 (페이로드는 읽지 않음)
python scripts/vscode_skill.py settings-sync status

# 다중 루트 작업 영역 도우미
python scripts/vscode_skill.py workspace info --ProjectPath /path/to/project
python scripts/vscode_skill.py workspace folder-settings-get --ProjectPath /path --Folder frontend
python scripts/vscode_skill.py workspace folder-settings-set --ProjectPath /path --Folder frontend --SettingKey editor.defaultFormatter --SettingValue dbaeumer.vscode-eslint --Apply

설정 동기화는 절대로 프로그래밍 방식으로 활성화 또는 비활성화되지 않습니다 — 스킬은 동기화 저장소 폴더가 존재하는지만 보고합니다. 우발적인 데이터 유출을 방지하려면 VS Code 계정 UI를 통해 활성화/비활성화하십시오.

원격 개발

• ssh open은 vscode-remote://ssh-remote+<host><path> URI를 구성하고 --folder-uri와 함께 해석된 CLI를 실행합니다.
• wsl open은 유사하게 vscode-remote://wsl+<distro><path> URI를 구성합니다.
• ssh smoke는 ssh -V, ssh -G <host>, Test-NetConnection을 실행하여 하위 계층을 확인합니다. Remote-SSH 확장이 설치되었거나 VS Code 서버가 시작되었음을 보장하지는 않습니다.

심층적인 원격 문제 해결을 위해서는 도움말 → 개발자 도구 전환, Remote-SSH 확장 출력 채널 또는 관련 제품의 workspaceStorage 항목을 확인하십시오.

테스트

번들된 run_vscode_skill_tests.py는 기본적으로 안전한 쓰기 금지 검사를 실행합니다:

python -X utf8 scripts/run_vscode_skill_tests.py --basic

선택적 그룹 (해당 환경 필요):

python -X utf8 scripts/run_vscode_skill_tests.py --include-python-venv