sessions: improve AI readiness of skill and instruction files#316239
Merged
Conversation
- Restructure SKILL.md: remove duplicated content, add mandatory pre-change reads (coding guidelines, source-code-organization), add 'When to read' column to spec table, make valid-layers-check mandatory, add common pitfalls section - Enhance sessions.instructions.md: add architecture overview, internal layer diagram, core services table, key development patterns (menus, context keys, observables), and learnings section - Remove window isolation references (not applicable) - Remove Development Recipes from skill (already in SESSIONS.md) - Add explicit 'Before Making Any Changes' mandatory reads block to ensure coverage in all harnesses (not just VS Code Copilot) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the AI-facing guidance for working in src/vs/sessions/ by restructuring the sessions skill file and expanding the sessions instruction file to better communicate layering constraints, core APIs, and common development patterns.
Changes:
- Reworked
.github/skills/sessions/SKILL.mdto include mandatory prerequisite reads, “when to read” triggers for specs, common pitfalls, and explicit validation requirements. - Expanded
.github/instructions/sessions.instructions.mdwith architecture/layering diagrams, core service pointers, contribution/menus/context-key guidance, and observable usage examples.
Show a summary per file
| File | Description |
|---|---|
| .github/skills/sessions/SKILL.md | Restructures the sessions skill into a shorter, more action-oriented checklist with spec triggers, pitfalls, and validation steps. |
| .github/instructions/sessions.instructions.md | Adds higher-level architecture/layering guidance plus concrete development patterns (entry points, menus, context keys, observables). |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 4
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Add SESSIONS_LIST.md covering the sessions list features: grouping, filtering, pinning, read/unread, navigation, mobile adaptations, menu entry points for contributing actions, and available context keys. Update SESSIONS.md with a cross-reference and SKILL.md with the new spec in the documents table. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lramos15
approved these changes
May 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves the
sessionsskill and instruction files so AI coding agents can work more effectively onsrc/vs/sessions/without extensive manual guidance.Changes
.github/skills/sessions/SKILL.md(restructured, now lean ~60 lines):coding-guidelines.instructions.mdandsource-code-organization.instructions.md— ensures coverage across all harnesses, not just VS Code Copilot where these are auto-injected viaapplyTovalid-layers-checkmandatory in the validation section.github/instructions/sessions.instructions.md(enhanced):vs/sessions→vs/workbench→vs/editor→vs/platform→vs/baselayeringcontrib/*must NOT importcontrib/providers/*)ISessionsManagementService,ISessionsProvidersService,ISession/IChat)Why
These files are the primary guide for AI agents working in the sessions codebase. Without explicit mandatory reads, models may skip layering checks and produce import violations. Without actionable "when to read" triggers, models may skip spec documents that are critical for specific task types.