VS Code Extension Builder
Build professional VS Code extensions with proper architecture, best practices, and complete tooling support.
Quick Start
For immediate extension creation:
Initialize: Run npx --package yo --package generator-code -- yo code Choose type: New Extension (TypeScript) Fill details: Name, identifier, description Develop: Open in VS Code, press F5 to debug Test: Run commands in Extension Development Host Package: Run vsce package when ready
For detailed guidance, follow the workflow below.
Extension Types
Choose the type that matches your needs:
Command Extension: Add commands to Command Palette (simplest, most common) Language Support: Syntax highlighting, IntelliSense, formatting Webview Extension: Custom UI panels with HTML/CSS/JS Tree View: Custom sidebar views with hierarchical data Debugger: Add debugging support for languages Theme: Color themes, file icon themes Snippet Provider: Code snippets for languages Core Workflow 1. Gather Requirements
Ask user about:
Purpose: What should the extension do? Type: Which extension type? (command, language, webview, etc.) Features: Specific functionality needed UI: Commands, views, panels, status bar items? Activation: When should it activate? 2. Choose Extension Type & Architecture
Based on requirements, select appropriate pattern:
Simple Command Extension (most common):
Single responsibility Command Palette integration Quick to build
Language Extension:
Syntax highlighting (TextMate grammar) Language server for IntelliSense Complex but powerful
Webview Extension:
Custom UI needed Rich interactions More complex state management
See extension-anatomy.md for detailed structure.
- Initialize Project
Option A: Use Yeoman Generator (Recommended)
npx --package yo --package generator-code -- yo code
Fill in:
Type: New Extension (TypeScript) Name: User-friendly name Identifier: lowercase-with-hyphens Description: Clear purpose Git: Yes Bundler: esbuild (recommended) or webpack Package manager: npm
Option B: Use Templates
For specific patterns, copy from assets/templates/:
command-extension/ - Command-based extension language-support/ - Language extension starter webview-extension/ - Webview-based extension 4. Implement Core Functionality
For Command Extensions:
Define command in package.json: { "contributes": { "commands": [{ "command": "extension.commandId", "title": "Command Title" }] } }
Register command in extension.ts: export function activate(context: vscode.ExtensionContext) { let disposable = vscode.commands.registerCommand('extension.commandId', () => { vscode.window.showInformationMessage('Hello from Extension!'); }); context.subscriptions.push(disposable); }
For Language Extensions: See common-apis.md for language features APIs.
For Webview Extensions: See common-apis.md for webview creation patterns.
- Configure Activation & Contributions
Activation Events determine when your extension loads:
onCommand: When command is invoked onLanguage: When file type opens onView: When tree view becomes visible *: On startup (avoid if possible)
See activation-events.md for complete reference.
Contributions declare extension capabilities in package.json:
commands: Command Palette entries menus: Context menu items keybindings: Keyboard shortcuts languages: Language support views: Tree views configuration: Settings 6. Test & Debug
Local Testing:
Press F5 in VS Code to launch Extension Development Host Test commands and features Check Debug Console for logs Set breakpoints for debugging
Automated Testing:
Unit tests: Test business logic Integration tests: Test VS Code API interactions Use @vscode/test-electron for testing
Common Issues:
Command not appearing: Check contributes.commands and activation events Extension not activating: Verify activation events in package.json API errors: Check VS Code API version compatibility 7. Package & Distribute
Prepare for Publishing:
Update README.md with features and usage Add extension icon (128x128 PNG) Set repository URL in package.json Add LICENSE file Test thoroughly
Package Extension:
npm install -g @vscode/vsce vsce package
Creates .vsix file for distribution.
Publish to Marketplace:
vsce publish
Requires Azure DevOps personal access token.
Common Patterns Pattern 1: Simple Command
Quick command that shows information:
vscode.commands.registerCommand('extension.showInfo', () => { vscode.window.showInformationMessage('Information message'); });
Pattern 2: Command with User Input
Get input before executing:
vscode.commands.registerCommand('extension.greet', async () => {
const name = await vscode.window.showInputBox({
prompt: 'Enter your name'
});
if (name) {
vscode.window.showInformationMessage(Hello, ${name}!);
}
});
Pattern 3: File Operation Command
Work with active editor:
vscode.commands.registerCommand('extension.processFile', () => { const editor = vscode.window.activeTextEditor; if (!editor) { vscode.window.showErrorMessage('No active editor'); return; }
const document = editor.document; const text = document.getText(); // Process text... });
Pattern 4: Status Bar Item
Show persistent status:
const statusBarItem = vscode.window.createStatusBarItem( vscode.StatusBarAlignment.Right, 100 ); statusBarItem.text = "$(check) Ready"; statusBarItem.show(); context.subscriptions.push(statusBarItem);
Reference Navigation
Load these references as needed:
extension-anatomy.md: When you need details about:
Extension structure and file organization package.json manifest fields Entry point and lifecycle hooks Extension context and disposables
common-apis.md: When implementing:
Window and editor operations Workspace and file system access Language features (IntelliSense, diagnostics) Webview creation and messaging Tree views and custom UI
activation-events.md: When configuring:
When extension should load Performance optimization Lazy loading strategies
best-practices.md: When considering:
UX guidelines and design patterns Performance optimization Security considerations Testing strategies Publishing guidelines Key Principles Performance Lazy load: Use specific activation events, not * Async operations: Use async/await for I/O Dispose resources: Clean up subscriptions Minimize startup: Defer heavy operations User Experience Clear commands: Descriptive titles and categories Feedback: Show progress for long operations Error handling: Helpful error messages Consistent UI: Follow VS Code conventions Code Quality TypeScript: Use strict mode for type safety Error handling: Try-catch for all operations Logging: Use console.log for debugging Testing: Write tests for critical functionality Troubleshooting Extension Not Appearing Verify package.json syntax (valid JSON) Check main field points to compiled output Ensure activation events are correct Reload window: Developer: Reload Window Command Not Working Check command ID matches in package.json and code Verify activation event includes the command Check Debug Console for errors Ensure command is registered in activate() Build Errors Run npm install to install dependencies Check TypeScript configuration Verify VS Code API version compatibility Update @types/vscode if needed Examples by Use Case Add Command to Format Code Type: Command extension Activation: onCommand Implementation: Get editor text, format, replace UI: Command Palette entry Add Syntax Highlighting Type: Language extension Activation: onLanguage:mylang Implementation: TextMate grammar in JSON UI: Automatic on file open Add Custom Sidebar View Type: Tree view extension Activation: onView:myView Implementation: TreeDataProvider interface UI: Activity bar icon + sidebar panel Add Quick Pick Menu Type: Command extension with UI Activation: onCommand Implementation: showQuickPick with items UI: Searchable dropdown menu Resources in This Skill references/: Detailed documentation (load as needed) assets/templates/: Starting templates for common patterns Official docs: https://code.visualstudio.com/api Related Skills
For code quality and architecture review of your extension code:
detect-code-smells: Check extension code quality security-pattern-check: Security review for extensions suggest-performance-fix: Optimize extension performance Notes
This skill provides the complete workflow for VS Code extension development, from initial concept to published extension. Use progressive disclosure: start with Quick Start for simple cases, dive into references for complex requirements. Templates in assets/ provide copy-paste starting points for common patterns.