Sessions
Implement or fix features in VS Code’s Agents window by following layering, layout, and contribution specs before editing `src/vs/sessions/`.
Overview
sessions is an agent skill for the Build phase that guides VS Code Agents window implementation using mandatory specs, layer rules, and layout documentation.
Install
npx skills add https://github.com/microsoft/vscode --skill sessionsWhat is this skill?
- Mandatory pre-read of coding-guidelines and source-code-organization instructions before any `src/vs/sessions/` change
- Layer hierarchy in LAYERS.md: core → services → contrib → providers with ESLint import restrictions
- Layout spec for fixed grid: Sidebar | ChatBar | AuxiliaryBar plus modal editor system
- Spec table maps each document to when to read it; implementation changes must update matching specs
- Internal layer stack: core → services → contrib → providers
- Fixed grid layout: Sidebar | ChatBar | AuxiliaryBar
Adoption & trust: 1.3k installs on skills.sh; 186k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are changing Agents window code without knowing which spec to read, breaking layer imports, or desyncing docs from behavior.
Who is it for?
Developers contributing to VS Code’s agents-first UI who need enforced architecture context before every edit.
Skip if: End users installing extensions only, or work outside `src/vs/sessions/` without reading the mapped specs.
When should I use this skill?
When implementing features or fixing issues in the Agents window in `src/vs/sessions/`.
What do I get? / Deliverables
You implement or fix sessions features in compliance with LAYERS.md and LAYOUT.md and keep the corresponding spec updated.
- Spec-aligned code changes under sessions with updated specification documents
Recommended Skills
Journey fit
Agents-window work is core product engineering for an agent-first IDE surface, which sits in Build. The skill documents chat widgets, menus, contributions, and entry points—canonical agent-tooling UI architecture.
How it compares
Use as in-repo architectural runbook, not as a generic “build a chat UI” starter template.
Common Questions / FAQ
Who is sessions for?
Engineers implementing or debugging the VS Code Agents window and related contributions in the sessions source tree.
When should I use sessions?
During Build agent-tooling whenever you add features, fix bugs, or refactor imports under `src/vs/sessions/`, especially before cross-module work.
Is sessions safe to install?
It is documentation-driven guidance for a known codebase; review Security Audits on this page and follow normal code-review practices for your fork.
SKILL.md
READMESKILL.md - Sessions
## Before Making Any Changes **MANDATORY:** Before writing or modifying any code in `src/vs/sessions/`, you **must** read these documents: 1. **`.github/instructions/coding-guidelines.instructions.md`** — Naming conventions, code style, string localization, disposable management, and DI patterns. 2. **`.github/instructions/source-code-organization.instructions.md`** — Layers, target environments, dependency injection, and folder structure conventions. Then read the relevant spec for the area you are changing (see table below). If you modify the implementation, you **must** update the corresponding spec to keep it in sync. ## Specification Documents | Document | Path | When to read | |----------|------|-------------| | Layer rules | `src/vs/sessions/LAYERS.md` | Before adding any cross-module imports. Defines the internal layer hierarchy (`core` → `services` → `contrib` → `providers`) with ESLint-enforced import restrictions. Key rule: `contrib/*` must NOT import from `contrib/providers/*`. | | Layout spec | `src/vs/sessions/LAYOUT.md` | Before changing any part, grid structure, titlebar, or CSS. Documents the fixed grid layout (Sidebar \| ChatBar \| AuxiliaryBar), part positions, the modal editor system, per-session layout state persistence, and the titlebar's three-section design. | | Sessions spec | `src/vs/sessions/SESSIONS.md` | Before changing session/provider interfaces or data flow. Covers the pluggable provider model (`ISessionsProvider` → `ISessionsProvidersService` → `ISessionsManagementService`), `ISession`/`IChat` interfaces, observable state propagation, workspace/folder model, and session type system. | | Sessions list spec | `src/vs/sessions/SESSIONS_LIST.md` | Before changing the sessions sidebar list. Covers the tree widget (`WorkbenchObjectTree`), renderers, grouping (workspace/date), filtering (type/status/archived/read), pinning, read/unread state, workspace capping, mobile adaptations, storage keys, and registered actions. | | Mobile spec | `src/vs/sessions/MOBILE.md` | Before adding any phone-specific UI. Covers the mobile part subclass architecture, viewport classification (phone < 640px), `MobileTitlebarPart`, drawer-based sidebar, `MobilePickerSheet`, view/action gating with `IsPhoneLayoutContext`, and the desktop → mobile component mapping. | | AI Customizations | `src/vs/sessions/AI_CUSTOMIZATIONS.md` | Before working on the customization editor or tree view. Documents the management editor (in `vs/workbench`) and the tree view/overview (in `vs/sessions/contrib/aiCustomizationTreeView`). | ## Common Pitfalls - **Wrong menu IDs**: Never use `MenuId.*` from `vs/platform/actions` for Agents window UI. Always use `Menus.*` from `browser/menus.ts`. - **Events instead of observables**: Session state must flow through `IObservable`, not `Event`. Use `autorun`/`derived` for reactive UI, not `onDid*` event listeners. - **Importing from providers**: Non-provider `contrib/*` code must never import from `contrib/providers/*`. Extract shared interfaces to `services/` or `common/`. - **Missing entry point import**: New contribution files must be imported in the appropriate `sessions.*.main.ts` entry point to be loaded (for example `sessions.common.main.ts`, `sessions.desktop.main.ts`, `sessions.web.main.ts`, or `sessions.web.main.internal.ts`). - **Modifying workbench code**: Prefer extending/wrapping workbench classes in the sessions layer over modifying shared workbench components. ## Validating Changes You **must** run these checks before declaring work complete: 1. `npm run compile-check-ts-native` — TypeScript compilation check. **Do not run `tsc` directly.** 2. `npm run valid-layers-check` — **MANDATORY.** Catches layering violations