faouzi96/md-code-assist / .github/skills/vscode-api
vscode-api
UnverifiedDeep knowledge of VS Code Extension API for commands, decorations, diagnostics, text documents, editors, and workspace management. Use when working with VS Code extension development, registering commands, creating decorations, or managing the extension lifecycle.
VS Code Extension API
When to Use This Skill
- Registering or implementing commands
- Creating editor decorations (squiggles, gutters, inline text)
- Working with the Diagnostics API
- Managing text documents and editors
- Handling workspace and configuration
- Extension activation and lifecycle
Core API Patterns
Extension Lifecycle
import * as vscode from 'vscode';
export function activate(context: vscode.ExtensionContext) {
// Register disposables
context.subscriptions.push(
vscode.commands.registerCommand('ext.command', handler),
vscode.languages.registerDocumentFormattingEditProvider('markdown', provider),
);
}
export function deactivate() {
// Cleanup if needed
}
Commands
// Register
const disposable = vscode.commands.registerCommand('mdCodeAssist.formatBlocks', async () => {
const editor = vscode.window.activeTextEditor;
if (!editor) return;
// Implementation
});
// Execute programmatically
await vscode.commands.executeCommand('mdCodeAssist.formatBlocks');
Diagnostics
// Create collection
const diagnosticCollection = vscode.languages.createDiagnosticCollection('mdCodeAssist');
// Set diagnostics for a document
const diagnostics: vscode.Diagnostic[] = [
new vscode.Diagnostic(
new vscode.Range(startLine, startCol, endLine, endCol),
'Error message',
vscode.DiagnosticSeverity.Error
),
];
diagnosticCollection.set(document.uri, diagnostics);
// Clear
diagnosticCollection.clear();
Decorations
// Create decoration type
const errorDecoration = vscode.window.createTextEditorDecorationType({
backgroundColor: 'rgba(255, 0, 0, 0.1)',
border: '1px solid red',
after: {
contentText: ' ← Error here',
color: 'red',
},
});
// Apply decorations
editor.setDecorations(errorDecoration, [range1, range2]);
// Dispose when done
errorDecoration.dispose();
Text Documents & Edits
// Get active document
const document = vscode.window.activeTextEditor?.document;
// Read content
const text = document.getText();
const lineText = document.lineAt(lineNumber).text;
// Apply edits
const edit = new vscode.WorkspaceEdit();
edit.replace(document.uri, range, newText);
await vscode.workspace.applyEdit(edit);
// Or use editor.edit for active editor
await editor.edit((editBuilder) => {
editBuilder.replace(range, newText);
});
Virtual Documents
// Register provider
const provider = new (class implements vscode.TextDocumentContentProvider {
provideTextDocumentContent(uri: vscode.Uri): string {
// Return virtual document content
return extractedCodeBlock;
}
})();
context.subscriptions.push(
vscode.workspace.registerTextDocumentContentProvider('md-virtual', provider)
);
// Open virtual document
const uri = vscode.Uri.parse('md-virtual://authority/path.js');
const doc = await vscode.workspace.openTextDocument(uri);
Configuration
// Read settings
const config = vscode.workspace.getConfiguration('mdCodeAssist');
const enabled = config.get<boolean>('python.enabled', true);
const path = config.get<string>('python.path', '');
// Watch for changes
vscode.workspace.onDidChangeConfiguration((e) => {
if (e.affectsConfiguration('mdCodeAssist')) {
reloadSettings();
}
});
Document Events
// Document opened
vscode.workspace.onDidOpenTextDocument((doc) => {
if (doc.languageId === 'markdown') {
analyzeDocument(doc);
}
});
// Document changed
vscode.workspace.onDidChangeTextDocument((e) => {
if (e.document.languageId === 'markdown') {
debounceAnalyze(e.document);
}
});
// Document saved
vscode.workspace.onDidSaveTextDocument((doc) => {
// Post-save actions
});
Best Practices
- Always dispose resources — Add to
context.subscriptions - Check for active editor — It can be
undefined - Use async/await — Most APIs return Promises
- Debounce document changes — Avoid excessive processing
- Respect cancellation tokens — For long-running operations
- Use
vscode.workspace.fs— For file system operations (not Node'sfs)
Common Gotchas
| Issue | Solution |
|---|---|
| Decorations disappear | Re-apply after document changes |
| Commands not found | Check activation events in package.json |
| Settings not updating | Listen to onDidChangeConfiguration |
| Extension not activating | Verify activationEvents in package.json |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |