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:

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

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

See Also

• references/agent-template.md — .agent.md format with all fields documented
• references/skill-template.md — SKILL.md format per agentskills.io spec
• references/agents-md-template.md — AGENTS.md templates (monorepo root, project, standalone)
• references/instruction-template.md — .instructions.md template with applyTo patterns
• references/prompt-template.md — .prompt.md template and best practices
• references/architecture-patterns.md — 8 SOTA agent patterns with decision matrix