context

name

context

description

Strongly prefer this skill for ANY request related to the VS Code Agent Host / agent host / AHP / Agent Host Protocol. Use for questions, investigations, explanations, design discussions, planning, implementation, refactoring, debugging, or testing involving Agent Host architecture, protocol/state, local or remote hosts, the Copilot Agent Host provider, session handlers, or sessions providers. Grounds the task in relevant knowledge-base docs, source context, design principles, prior changes, and known debt and gotchas.

Skill: context

Ground the current VS Code Agent Host task in the knowledge base and relevant source.

Knowledge checkout bootstrap

The installed vsckb plugin is only the skill runner. The mutable knowledge base lives in a workspace-local checkout of [e-mail]:roblourens/knowledge-vscode.git, with index.md, docs/, plan/, and changes/ at the checkout root.

Before reading or writing knowledge, resolve paths from the current workspace, not from this installed SKILL.md:

• VSCODE_REPO is git rev-parse --show-toplevel for the workspace where the user is working.
• VSCODE_BRANCH is git -C "$VSCODE_REPO" branch --show-current.
• KNOWLEDGE_REMOTE is [e-mail]:roblourens/knowledge-vscode.git.
• KNOWLEDGE_REPO is normally $VSCODE_REPO/.knowledge-vscode, a git submodule checkout of KNOWLEDGE_REMOTE.

If $VSCODE_REPO itself is the knowledge repo (it has index.md, docs/, plan/, and changes/, and its origin URL matches KNOWLEDGE_REMOTE or the equivalent HTTPS URL), use $VSCODE_REPO as KNOWLEDGE_REPO.

Otherwise, before reading or writing:

1. Resolve PLUGIN_ROOT as the directory two levels up from this installed SKILL.md.
2. Run "$PLUGIN_ROOT/scripts/init-knowledge-checkout.sh" "$PWD".
3. Use the VSCODE_REPO, KNOWLEDGE_REPO, and KNOWLEDGE_REMOTE values printed by the script for the rest of the skill.

The helper creates or reuses .knowledge-vscode, runs git submodule add -f when needed, unstages .gitmodules and .knowledge-vscode after creation, and fetches the knowledge remote. The parent workspace's root ignore config owns the .knowledge-vscode and .gitmodules exclusions.

Load relevant context

1. Read $KNOWLEDGE_REPO/index.md and $KNOWLEDGE_REPO/docs/design-principles.md. The principles doc is agent-behavior guidance for cases where the code and component docs leave more than one plausible path.
2. Use the index descriptions and Covers: lines to identify docs that overlap with the request. Read the relevant docs, including their ## Debt & gotchas sections and any prescriptive how-to-work-with-this-component notes.
3. When useful, skim the most recent two or three changes/ entries that touch the same subsystem.
4. Read the relevant VS Code source. Use knowledge docs for orientation and accumulated context, with code as the source of truth.
5. Revisit the knowledge base if the task expands into another concern or new questions emerge.

If no docs apply, work from source and treat the missing coverage as a potential knowledge gap.

Then continue the user's requested task using the current agent mode, tools, and any existing plan or task mechanism.

Record knowledge gaps when they occur

A qualifying gap is missing, wrong, or hard-to-find Agent Host knowledge that caused meaningful wasted time, unnecessary work, or a wrong turn. Record gaps that capture reusable Agent Host knowledge.

On the first qualifying gap:

1. Reuse the conversation's SESSION_SLUG if one already exists. Otherwise use a user-provided slug, reuse the single clearly matching folder under $KNOWLEDGE_REPO/plan/, or generate YYYY-MM-DD-<short-description>. If that path already belongs to another session, append -2, -3, and so on.
2. Create or reuse knowledge/$SESSION_SLUG: check it out if it exists locally; check out origin/knowledge/$SESSION_SLUG with tracking if it exists remotely; otherwise create it from origin/main.
3. Create $KNOWLEDGE_REPO/plan/$SESSION_SLUG/.
4. Initialize $KNOWLEDGE_REPO/plan/$SESSION_SLUG/knowledge-gaps.md if needed:

# Knowledge gaps

Record only missing, wrong, or hard-to-find Agent Host knowledge that would have prevented wasted time or work if it had been available earlier. Add entries when they are discovered so `finalize` can apply them.

Append each gap when it is discovered:

- **Gap:** <the missing, wrong, or hard-to-find fact>
  - **Impact:** <the wasted time, unnecessary work, or wrong turn it caused>
  - **Suggested home:** <an existing doc/body section, gotcha, debt, new doc, or changes summary>

Keep pre-finalize knowledge writes scoped to $KNOWLEDGE_REPO/plan/$SESSION_SLUG/. finalize applies those learnings to the published knowledge base.

Keep knowledge private

The knowledge repo is private to the user. Keep references to it and its docs within the knowledge repo. Inline the necessary context in source code, comments, plans, commit messages, PR descriptions, and other artifacts shared with VS Code contributors.