Copilot instructions

1---
2description: Architecture documentation for VS Code AI Customization view. Use when working in `src/vs/workbench/contrib/chat/browser/aiCustomization`
3applyTo: 'src/vs/workbench/contrib/chat/browser/aiCustomization/**'
4---
5 
6# AI Customization View
7 
8The AI Customization view provides a unified view for discovering and managing AI customization 'artifacts' (customizations that augment LLM prompts or behavior).
9 
10Examples 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.
11 
12## Overview
13 
14The view displays a hierarchical tree structure:
15 
16```
17AI Customization (View Container)
18└── AI Customization (Tree View)
19    ├── Custom Agents (.agent.md files)
20    │   ├── Workspace
21    │   │   └── agent files...
22    │   ├── User
23    │   │   └── agent files...
24    │   └── Extensions
25    │       └── agent files...
26    ├── Skills (SKILL.md files)
27    │   └── (same storage structure)
28    ├── Instructions (.instructions.md files)
29    │   └── (same storage structure)
30    └── Prompts (.prompt.md files)
31        └── (same storage structure)
32```
33 
34**Key Features:**
35- 3-level tree hierarchy: Category → Storage Group → Files
36- Auto-expands category nodes on initial load and refresh to show storage groups
37- Symbol-based root element for type safety
38- Double-click to open files in editor
39- Context menu support with Open and Run Prompt actions
40- Toolbar actions: New dropdown, Refresh, Collapse All
41- Skill names parsed from frontmatter with fallback to folder name
42- Responsive to IPromptsService change events
43 
44## File Structure
45 
46All files are located in `src/vs/workbench/contrib/chat/browser/aiCustomization/`:
47 
48```
49aiCustomization/
50├── aiCustomization.ts              # Constants, IDs, and MenuIds
51├── aiCustomization.contribution.ts # View registration and actions
52├── aiCustomizationViews.ts         # Tree view pane implementation
53├── aiCustomizationIcons.ts         # Icon registrations
54└── media/
55    └── aiCustomization.css         # Styling
56```
57 
58## Key Constants (aiCustomization.ts)
59 
60- `AI_CUSTOMIZATION_VIEWLET_ID`: View container ID for sidebar
61- `AI_CUSTOMIZATION_VIEW_ID`: Unified tree view ID
62- `AI_CUSTOMIZATION_STORAGE_ID`: State persistence key
63- `AICustomizationItemMenuId`: Context menu ID
64- `AICustomizationNewMenuId`: New item submenu ID
65 
66## View Registration (aiCustomization.contribution.ts)
67 
68### View Container
69 
70Register sidebar container with:
71- ViewPaneContainer with `mergeViewWithContainerWhenSingleView: true`
72- Keyboard shortcut: Cmd+Shift+I
73- Location: Sidebar
74- Visibility: `when: ChatContextKeys.enabled` (respects AI disable setting)
75 
76### View Descriptor
77 
78Register single unified tree view:
79- Constructor: `AICustomizationViewPane`
80- Toggleable and moveable
81- Gated by `ChatContextKeys.enabled`
82 
83### Welcome Content
84 
85Shows markdown links to create new items when tree is empty.
86 
87## Toolbar Actions
88 
89**New Item Dropdown** - Submenu in view title:
90- Add icon in navigation group
91- Submenu contains: New Agent, New Skill, New Instructions, New Prompt
92- Each opens PromptFilePickers to guide user through creation
93 
94**Refresh** - ViewAction that calls `view.refresh()`
95 
96**Collapse All** - ViewAction that calls `view.collapseAll()`
97 
98All actions use `ViewAction<AICustomizationViewPane>` pattern and are gated by `when: view === AI_CUSTOMIZATION_VIEW_ID`.
99 
100## Tree View Implementation (aiCustomizationViews.ts)
101 
102### Tree Item Types
103 
104Discriminated union with `type` field:
105 
106**ROOT_ELEMENT** - Symbol marker for type-safe root
107 
108**IAICustomizationTypeItem** (`type: 'category'`)
109- Represents: Custom Agents, Skills, Instructions, Prompts
110- Contains: label, promptType, icon
111 
112**IAICustomizationGroupItem** (`type: 'group'`)
113- Represents: Workspace, User, Extensions
114- Contains: label, storage, promptType, icon
115 
116**IAICustomizationFileItem** (`type: 'file'`)
117- Represents: Individual prompt files
118- Contains: uri, name, description, storage, promptType
119 
120### Data Source
121 
122`UnifiedAICustomizationDataSource` implements `IAsyncDataSource`:
123 
124**getChildren logic:**
125- ROOT → 4 categories (agent, skill, instructions, prompt)
126- category → storage groups (workspace, user, extensions) that have items
127- group → files from `promptsService.listPromptFilesForStorage()` or `findAgentSkills()`
128 
129**Skills special handling:** Uses `findAgentSkills()` to get names from frontmatter instead of filenames
130 
131### Tree Renderers
132 
133Three specialized renderers for category/group/file items:
134- **Category**: Icon + bold label
135- **Group**: Uppercase label with descriptionForeground color
136- **File**: Icon + name with tooltip
137 
138### View Pane
139 
140`AICustomizationViewPane extends ViewPane`:
141 
142**Injected services:**
143- IPromptsService - data source
144- IEditorService - open files
145- IMenuService - context menus
146 
147**Initialization:**
1481. Subscribe to `onDidChangeCustomAgents` and `onDidChangeSlashCommands` events
1492. Create WorkbenchAsyncDataTree with 3 renderers and data source
1503. Register handlers: `onDidOpen` (double-click) → open file, `onContextMenu` → show menu
1514. Set input to ROOT_ELEMENT and auto-expand categories
152 
153**Auto-expansion:**
154- After setInput, iterate root children and expand each category
155- Reveals storage groups without user interaction
156- Applied on both initial load and refresh
157 
158**Public API:**
159- `refresh()` - Reload tree and re-expand categories
160- `collapseAll()` - Collapse all nodes
161- `expandAll()` - Expand all nodes
162 
163## Context Menu Actions
164 
165Menu ID: `AICustomizationItemMenuId`
166 
167**Actions:**
168- **Open** - Opens file in editor using IEditorService
169- **Run Prompt** - Only for prompt files, invokes chat with prompt
170 
171**URI handling:** Actions must handle both URI objects and serialized strings
172- Check `URI.isUri(context)` first
173- Parse string variants with `URI.parse()`
174 
175**Context passing:**
176- Serialize context as `{ uri: string, name: string, promptType: PromptsType }`
177- Use `shouldForwardArgs: true` in getMenuActions
178- Only show context menu for file items (not categories/groups)
179 
180## Icons (aiCustomizationIcons.ts)
181 
182Themed icons using `registerIcon(id, codicon, label)`:
183 
184**View/Types:**
185- aiCustomizationViewIcon - Codicon.sparkle
186- agentIcon - Codicon.copilot
187- skillIcon - Codicon.lightbulb
188- instructionsIcon - Codicon.book
189- promptIcon - Codicon.bookmark
190 
191**Storage:**
192- workspaceIcon - Codicon.folder
193- userIcon - Codicon.account
194- extensionIcon - Codicon.extensions
195 
196## Styling (media/aiCustomization.css)
197 
198**Layout:** Full height view and tree container
199 
200**Tree items:** Flex layout with 16px icon + text, ellipsis overflow
201 
202**Categories:** Bold font-weight
203 
204**Groups:** Uppercase, small font (11px), letter-spacing, descriptionForeground color
205 
206## Integration Points
207 
208**IPromptsService:**
209- `listPromptFilesForStorage(type, storage)` - Get files for a type/storage combo
210- `findAgentSkills()` - Get skills with names parsed from frontmatter
211- `onDidChangeCustomAgents` - Refresh on agent changes
212- `onDidChangeSlashCommands` - Refresh on command changes
213 
214**PromptsType enum:** `instructions | prompt | agent | skill`
215 
216**PromptsStorage enum:** `local` (workspace) | `user` | `extension`
217 
218**AI Feature Gating:** View gated by `ChatContextKeys.enabled` (respects `chat.disableAIFeatures` setting)
219 
220**Registration:** Import `./aiCustomization/aiCustomization.contribution.js` in `chat.contribution.ts`
221 
222---
223 
224*Update this file when making architectural changes to the AI Customization view.*
225