vscode/.github/instructions/ai-customization.instructions.md

description, applyTo

description	applyTo
Architecture documentation for VS Code AI Customization view. Use when working in `src/vs/workbench/contrib/chat/browser/aiCustomization`	src/vs/workbench/contrib/chat/browser/aiCustomization/**

AI Customization View

The AI Customization view provides a unified view for discovering and managing AI customization 'artifacts' (customizations that augment LLM prompts or behavior).

Examples of these include: Custom Agents, Skills, Instructions, and Prompts. It surfaces prompt files that are typically hidden in .github/ folders, user data directories, workspace settings, or exposed via extensions.

Overview

The view displays a hierarchical tree structure:

AI Customization (View Container)
└── AI Customization (Tree View)
    ├── Custom Agents (.agent.md files)
    │   ├── Workspace
    │   │   └── agent files...
    │   ├── User
    │   │   └── agent files...
    │   └── Extensions
    │       └── agent files...
    ├── Skills (SKILL.md files)
    │   └── (same storage structure)
    ├── Instructions (.instructions.md files)
    │   └── (same storage structure)
    └── Prompts (.prompt.md files)
        └── (same storage structure)

Key Features:

• 3-level tree hierarchy: Category → Storage Group → Files
• Auto-expands category nodes on initial load and refresh to show storage groups
• Symbol-based root element for type safety
• Double-click to open files in editor
• Context menu support with Open and Run Prompt actions
• Toolbar actions: New dropdown, Refresh, Collapse All
• Skill names parsed from frontmatter with fallback to folder name
• Responsive to IPromptsService change events

File Structure

All files are located in src/vs/workbench/contrib/chat/browser/aiCustomization/:

aiCustomization/
├── aiCustomization.ts              # Constants, IDs, and MenuIds
├── aiCustomization.contribution.ts # View registration and actions
├── aiCustomizationViews.ts         # Tree view pane implementation
├── aiCustomizationIcons.ts         # Icon registrations
└── media/
    └── aiCustomization.css         # Styling

Key Constants (aiCustomization.ts)

• AI_CUSTOMIZATION_VIEWLET_ID: View container ID for sidebar
• AI_CUSTOMIZATION_VIEW_ID: Unified tree view ID
• AI_CUSTOMIZATION_STORAGE_ID: State persistence key
• AICustomizationItemMenuId: Context menu ID
• AICustomizationNewMenuId: New item submenu ID

View Registration (aiCustomization.contribution.ts)

View Container

Register sidebar container with:

• ViewPaneContainer with mergeViewWithContainerWhenSingleView: true
• Keyboard shortcut: Cmd+Shift+I
• Location: Sidebar
• Visibility: when: ChatContextKeys.enabled (respects AI disable setting)

View Descriptor

Register single unified tree view:

• Constructor: AICustomizationViewPane
• Toggleable and moveable
• Gated by ChatContextKeys.enabled

Welcome Content

Shows markdown links to create new items when tree is empty.

Toolbar Actions

New Item Dropdown - Submenu in view title:

• Add icon in navigation group
• Submenu contains: New Agent, New Skill, New Instructions, New Prompt
• Each opens PromptFilePickers to guide user through creation

Refresh - ViewAction that calls view.refresh()

Collapse All - ViewAction that calls view.collapseAll()

All actions use ViewAction<AICustomizationViewPane> pattern and are gated by when: view === AI_CUSTOMIZATION_VIEW_ID.

Tree View Implementation (aiCustomizationViews.ts)

Tree Item Types

Discriminated union with type field:

ROOT_ELEMENT - Symbol marker for type-safe root

IAICustomizationTypeItem (type: 'category')

• Represents: Custom Agents, Skills, Instructions, Prompts
• Contains: label, promptType, icon

IAICustomizationGroupItem (type: 'group')

• Represents: Workspace, User, Extensions
• Contains: label, storage, promptType, icon

IAICustomizationFileItem (type: 'file')

• Represents: Individual prompt files
• Contains: uri, name, description, storage, promptType

Data Source

UnifiedAICustomizationDataSource implements IAsyncDataSource:

getChildren logic:

• ROOT → 4 categories (agent, skill, instructions, prompt)
• category → storage groups (workspace, user, extensions) that have items
• group → files from promptsService.listPromptFilesForStorage() or findAgentSkills()

Skills special handling: Uses findAgentSkills() to get names from frontmatter instead of filenames

Tree Renderers

Three specialized renderers for category/group/file items:

• Category: Icon + bold label
• Group: Uppercase label with descriptionForeground color
• File: Icon + name with tooltip

View Pane

AICustomizationViewPane extends ViewPane:

Injected services:

• IPromptsService - data source
• IEditorService - open files
• IMenuService - context menus

Initialization:

1. Subscribe to onDidChangeCustomAgents and onDidChangeSlashCommands events
2. Create WorkbenchAsyncDataTree with 3 renderers and data source
3. Register handlers: onDidOpen (double-click) → open file, onContextMenu → show menu
4. Set input to ROOT_ELEMENT and auto-expand categories

Auto-expansion:

• After setInput, iterate root children and expand each category
• Reveals storage groups without user interaction
• Applied on both initial load and refresh

Public API:

• refresh() - Reload tree and re-expand categories
• collapseAll() - Collapse all nodes
• expandAll() - Expand all nodes

Context Menu Actions

Menu ID: AICustomizationItemMenuId

Actions:

• Open - Opens file in editor using IEditorService
• Run Prompt - Only for prompt files, invokes chat with prompt

URI handling: Actions must handle both URI objects and serialized strings

• Check URI.isUri(context) first
• Parse string variants with URI.parse()

Context passing:

• Serialize context as { uri: string, name: string, promptType: PromptsType }
• Use shouldForwardArgs: true in getMenuActions
• Only show context menu for file items (not categories/groups)

Icons (aiCustomizationIcons.ts)

Themed icons using registerIcon(id, codicon, label):

View/Types:

• aiCustomizationViewIcon - Codicon.sparkle
• agentIcon - Codicon.copilot
• skillIcon - Codicon.lightbulb
• instructionsIcon - Codicon.book
• promptIcon - Codicon.bookmark

Storage:

• workspaceIcon - Codicon.folder
• userIcon - Codicon.account
• extensionIcon - Codicon.extensions

Styling (media/aiCustomization.css)

Layout: Full height view and tree container

Tree items: Flex layout with 16px icon + text, ellipsis overflow

Categories: Bold font-weight

Groups: Uppercase, small font (11px), letter-spacing, descriptionForeground color

Integration Points

IPromptsService:

• listPromptFilesForStorage(type, storage) - Get files for a type/storage combo
• findAgentSkills() - Get skills with names parsed from frontmatter
• onDidChangeCustomAgents - Refresh on agent changes
• onDidChangeSlashCommands - Refresh on command changes

PromptsType enum: instructions | prompt | agent | skill

PromptsStorage enum: local (workspace) | user | extension

AI Feature Gating: View gated by ChatContextKeys.enabled (respects chat.disableAIFeatures setting)

Registration: Import ./aiCustomization/aiCustomization.contribution.js in chat.contribution.ts

---

Update this file when making architectural changes to the AI Customization view.