Agentic Workspace Skill

Expert guide for designing and implementing SOTA agentic architectures in multi-project VS Code workspaces. Covers the full stack: agents, skills, instructions, prompts, context engineering, and the interplay between them.

Core Principles

1. Progressive Disclosure (Token Efficiency)

Context is expensive. Load the minimum at startup, expand on demand:

Tier	What	When	Token Budget
Metadata	`name` + `description`	Always (startup)	~100 tokens/skill
Instructions	Full `SKILL.md` body	On activation	< 5 000 tokens
Resources	`references/`, `scripts/`, `assets/`	On demand	As needed

Rule: Every piece of context should earn its token cost. Challenge each element: "Does this justify its presence?"

2. Layered Context Architecture

Context flows from general to specific. More specific layers override less specific ones.

Layer 1  User-level instructions     (~/.agents/skills/, VS Code userdata)
Layer 2  Repository root             AGENTS.md + .github/copilot-instructions.md
Layer 3  Project root                project/AGENTS.md (nearest-file-wins)
Layer 4  Path-specific instructions  .github/instructions/*.instructions.md (applyTo globs)
Layer 5  Skills (triggered)          ~/.agents/skills/ + .github/skills/ (on activation)
Layer 6  Agents (when invoked)       .github/agents/*.agent.md
Layer 7  Prompts (when invoked)      .github/prompts/*.prompt.md

Nearest-file-wins: The nearest AGENTS.md in the directory tree takes precedence.

3. Separation of Concerns

Artifact	Purpose	Scope	Activation
Skill	Reusable capability with scripts/resources	CrossProject portable	Dynamically by task relevance
Instruction	Project-specific coding rules	Path-scoped or repo-wide	Auto by file match (`applyTo`)
Prompt	Reusable template for specific task	Workspace or user	Manually invoked
Agent	Role/persona with tools + handoffs	Workspace or user	Manually selected or via handoff
AGENTS.md	Context index and entry point for agents	Per directory tree	Always included

Protocol — Setting Up an Agentic Workspace

Step 1 — Audit Current State

List all existing .agent.md, SKILL.md, .instructions.md, .prompt.md, AGENTS.md files
Map the project structure (monorepo? multi-root? packages?)
Identify duplications, gaps, and context pollution risks
Check if global skills (~/.agents/skills/) are in lock file

Step 2 — Design the Agent Hierarchy

Choose the right architecture pattern (see references/architecture-patterns.md):

Linear Pipeline: Research → Plan → Implement → Review (simple, predictable)
Orchestrator-Workers: Supervisor routes to specialists (flexible, SOTA for complex tasks)
Swarm/Handoffs: Lightweight specialist handoffs (good for well-defined roles)

For most workspaces: Orchestrator at root + specialists per project/domain.

Step 3 — Define Agent Taxonomy

Root (shared across all projects)
├── Orchestrator  — task analysis + routing
├── Research      — web + codebase research, freshness validation
├── Plan          — read-only exploration + structured planning
└── Review        — QA, architecture compliance, testing validation

Project-specific (override or extend root agents)
├── Deploy        — deployment workflows
├── Migration     — database/API migrations
└── <domain>      — domain-specific specialist

Tool scoping by agent role:

Research: ['search', 'fetch', 'codebase', 'problems'] — read-only
Plan: ['search', 'codebase', 'problems'] — read-only
Review: ['search', 'codebase', 'problems', 'diagnostics'] — read-only
Implement: ['editFile', 'createFile', 'terminal', 'search', 'codebase'] — full access
Orchestrator: ['search', 'codebase'] — routing only (minimal tools)

Step 4 — Design the Skill Ecosystem

Global skills (~/.agents/skills/)        — cross-project, install via skills.sh or manual
Project skills (.github/skills/)         — project-specific, committed to repo

Decision criteria:

Will this skill be useful in >1 project? → Global
Is this tightly coupled to this project's stack? → Project-local
Does it need scripts or data files? → Use scripts/, references/, assets/ subdirs

Step 5 — Write Instructions (Path-Specific Context Injection)

Instructions auto-activate based on applyTo glob patterns. Cover every significant directory:

# Standard instruction set for a TypeScript project
applyTo: "src/core/**"          → domain rules (zero deps, Result pattern)
applyTo: "src/adapters/**"      → adapter rules (implement ports, DI injection)  
applyTo: "src/cli/**"           → CLI conventions (framework, one-file-per-command)
applyTo: "**/tests/**"          → test rules (Vitest, no infra deps for unit tests)
applyTo: "**/*.test.ts"         → same as above

Step 6 — Write AGENTS.md Files

One per project + one at monorepo root (if applicable):

Root AGENTS.md: Monorepo index (projects, shared agents, global skills, architecture)
Project AGENTS.md: Project-specific details (stack, commands, build/test, local skills)

See references/agents-md-template.md for templates.

Step 7 — Connect to MCP and VS Code

Add .vscode/mcp.json for MCP server auto-discovery
Add chat.agentFilesLocations in settings.json if agents live in non-standard paths
Ensure copilot-instructions.md is in root .github/ for GitHub-hosted projects

Step 8 — Verify

Checklist before considering the agentic setup complete:

Nearest-file-wins works (test by opening files in different subprojects)
All agents appear in Copilot Chat agents dropdown
Skills trigger correctly by description keyword match
Instructions activate only for matching applyTo patterns
AGENTS.md at each level is non-redundant with parent AGENTS.md
No secrets or credentials in any agent/skill/instruction file
Tool scoping is correct (read-only agents can't edit files)

Workspace File Structure (Reference)

monorepo-root/
├── AGENTS.md                                 ← Monorepo index (shared context)
├── .github/
│   ├── copilot-instructions.md               ← Repo-wide Copilot context
│   ├── agents/                               ← Shared agents (all projects)
│   │   ├── Orchestrator.agent.md
│   │   ├── Research.agent.md
│   │   ├── Plan.agent.md
│   │   └── Review.agent.md
│   ├── instructions/                         ← Cross-project path rules
│   │   ├── typescript.instructions.md        ← applyTo: "**/*.ts"
│   │   └── testing.instructions.md           ← applyTo: "**/tests/**"
│   ├── prompts/                              ← Shared reusable prompts
│   │   ├── smart-commit.prompt.md
│   │   └── code-review.prompt.md
│   └── skills/                              ← Optional project-specific skills
│
├── project-a/
│   ├── AGENTS.md                            ← Project-specific index (overrides root)
│   └── .github/
│       ├── agents/                          ← Project-specific agents
│       ├── instructions/                    ← Project-specific path rules
│       └── skills/                         ← Project-specific skills
│
└── project-b/
    ├── AGENTS.md
    └── .github/
        └── instructions/

Anti-Patterns to Avoid

Anti-Pattern	Problem	Fix
Duplicate AGENTS.md at multiple levels with same content	Context confusion, drift risk	Root = index, project = detail, no duplication
Monolithic agent doing Research + Plan + Review	Violates SRP, context bloat	Split into specialized agents with handoffs
Hardcoded project info in global skills	Global skills become un-reusable	Keep global skills generic, project context in local skills
Missing `applyTo` on instructions	Instructions activate everywhere, pollute context	Always set `applyTo` to narrowest appropriate glob
Agent with all tools (editFile + search + terminal)	No guardrails, risky agent	Scope tools by role (read-only for Research/Plan/Review)
Skills > 500 lines in SKILL.md	Context overload	Move detail to `references/` subdirectory
Prompts tightly coupled to one agent	Reduces reusability	Use `agent: "agent"` default, or bind explicitly per use case
No handoff graph	Agents are isolated silos	Define explicit handoffs with clear labels and prompts

agentic-workspace