Skills and Instructions

Skills System

Skill Structure

Each skill follows a standard layout:

.github/skills/{name}/
├── SKILL.md                    # Core overview (≤ 500 lines)
├── references/                 # Deep reference material (loaded on demand)
│   ├── detailed-guide.md
│   └── lookup-table.md
└── templates/                  # Template files (loaded on demand)
    └── artifact.template.md

Progressive Loading

Skills implement three levels of disclosure:

1. Level 1 — SKILL.md: Compact overview loaded when the agent reads the skill. Contains quick-reference tables, decision frameworks, and pointers to deeper content.

2. Level 2 — references/: Detailed guides, lookup tables, and protocol definitions. Loaded only when a specific sub-task requires deep knowledge.

3. Level 3 — templates/: Exact structural skeletons for artefact generation. Loaded only during the output generation phase.

Skill Catalog

The system contains skills across several domains. The full, always-current list is generated from .github/skills/*/SKILL.md and surfaced in the Architecture Explorer. The total count is computed by tools/registry/count-manifest.json. A grouped overview:

Domain	Skills
Azure Infrastructure	azure-defaults, azure-bicep-patterns, terraform-patterns, azure-validate
Azure Operations	azure-diagnostics, azure-adr, azure-deploy
Diagram & Chart	drawio, python-diagrams, mermaid
Artefact Generation	azure-artifacts, context-management
Documentation	docs-writer
Workflow and State	workflow-engine, golden-principles
Deployment	iac-common
GitHub Operations	github-operations
Terraform Tooling	terraform-search-import, terraform-test
Azure Plugin Skills	azure-prepare, azure-cost-optimization, azure-compute, azure-compliance, azure-rbac, azure-storage, azure-kusto, azure-quotas, azure-resources, azure-cloud-migrate, entra-app-registration
Microsoft Learn	microsoft-docs
Meta / Tooling	context-management

The skills domain table above is the live catalog. For the authoritative list of VS Code Copilot customization mechanisms (instructions, prompt files, custom agents, agent skills, MCP servers, hooks, plugins) see .github/copilot-instructions.md and the per-mechanism files under .github/instructions/.

Instruction System

Glob-Based Auto-Application

Instructions are not read explicitly by agents. They are injected automatically by VS Code Copilot when a matching file is in context. The applyTo glob pattern controls when each instruction activates:

Instruction	applyTo	Enforces
iac-bicep-best-practices	**/*.bicep	Bicep: security baseline, AVM, cost monitoring, repeatability
iac-terraform-best-practices	**/*.tf	Terraform: AVM-TF, provider pinning, naming, security baseline
iac-plan-best-practices	**/04-implementation-plan.md	IaC plan structure, governance alignment
azure-artifacts	**/agent-output/**/*.md	H2 template compliance for artefacts
agent-authoring	**/*.agent.md	Frontmatter standards for agents
agent-research-first	**/*.agent.md, agent-output, skills	Mandatory research-before-implementation
agent-skills	**/.github/skills/**/SKILL.md	Skill file format standards
astro	site/**/*.{astro,mjs,ts}	Astro/Starlight site conventions
drawio	**/*.drawio, **/*.drawio.svg	Draw.io diagram conventions
instructions	**/*.instructions.md	Meta: instruction file guidelines
markdown	**/*.md	Documentation standards
context-optimization	Agents, skills, instructions	Context window management rules
code-quality	**/*.{js,mjs,cjs,ts,tsx,jsx,py,ps1,sh,bicep,tf}	Review priorities and comment quality
docs-trigger	**/*.agent.md, **/.github/skills/**/SKILL.md, **/scripts/*.mjs	Trigger conditions for doc updates
docs	site/src/content/docs/**/*.md, site/src/content/docs/**/*.mdx	User-facing documentation standards
governance-discovery	**/04-governance-constraints.*	Azure Policy discovery requirements
github-actions	.github/workflows/*.yml	GitHub Actions workflow standards
javascript	**/*.{js,mjs,cjs}	JavaScript/Node.js conventions
json	**/*.{json,jsonc}	JSON/JSONC formatting
lesson-collection	agent-output/**/09-lessons-learned.*	Lessons-learned capture format
no-hardcoded-counts	**	Entity counts must come from count-manifest.json
python	**/*.py	Python coding conventions
shell	**/*.sh	Shell scripting best practices
powershell	**/*.ps1, **/*.psm1	PowerShell cmdlet best practices
prompt	**/*.prompt.md	Prompt file guidelines
no-heredoc	**	Prevents terminal heredoc corruption

When multiple instructions apply to the same file via overlapping applyTo globs, precedence rules determine which takes priority. See .github/instructions/references/precedence-matrix.md for the full matrix. Short version: Azure Policy compliance (Tier 1) always wins over domain IaC (Tier 2), which wins over cross-cutting cost rules (Tier 3), which wins over general code quality (Tier 4).

iac-bicep-best-practices.instructions.md and iac-terraform-best-practices.instructions.md are the track-specific instructions that enforce two mandatory rules across all IaC projects (Bicep and Terraform):

1. Cost Monitoring: Every deployment must include an Azure Budget resource with parameterised amount, forecast alerts at 80/100/120% thresholds, and anomaly detection alerts to a technicalContact parameter.
2. Repeatability (zero hardcoded values): Templates must deploy to any tenant/region/subscription without source-code modification. projectName must be a parameter with no default; all tag values reference parameters; .bicepparam/terraform.tfvars is the only place for project-specific defaults.

Enforcement Over Documentation

Golden Principle

Mechanical enforcement over documentation — if it can be a linter check, it should be one. Documentation is for humans; machines enforce rules.

Following the Golden Principle “Mechanical Enforcement Over Documentation,” every instruction has a corresponding validation script. The rule is: if it can be a linter check, it should be one. Documentation is for humans; machines enforce rules.

Creating a Custom Skill

This section walks through creating a new skill from scratch.

Step 1: Scaffold

Copy an existing skill (for example azure-defaults) as a starting point and rename the directory:

cp -r .github/skills/azure-defaults .github/skills/my-new-skill

The expected structure is:

.github/skills/my-new-skill/
├── SKILL.md          # Core overview (≤ 500 lines)
├── references/       # Deep reference material
└── templates/        # Template files for artifact generation

Authoring rules live in agent-skills.instructions.md. After scaffolding, run the sensei skill to iteratively improve frontmatter quality, and npm run lint:skills-format plus npm run validate:agents to verify.

Step 2: Write SKILL.md

The SKILL.md file requires YAML frontmatter:

---
name: my-new-skill
description: "Short description of the skill's purpose.
  USE FOR: keyword triggers.
  DO NOT USE FOR: anti-triggers."
compatibility: List of compatible agents
---
# My New Skill

Quick-reference tables, decision frameworks, and pointers to deeper content.

Frontmatter rules (from .github/instructions/agent-skills.instructions.md):

• name must match the folder name exactly
• description must be an inline string (not a YAML block scalar)
• Keep SKILL.md under 500 lines — move deep content to references/

Step 3: Add References and Templates

Use the three levels of disclosure:

Level	Directory	Loaded When	Content
1	SKILL.md	Agent reads the skill	Overview, quick-reference tables
2	references/	Sub-task needs deep knowledge	Detailed guides, lookup tables
3	templates/	Output generation phase	Structural skeletons for artifacts

Example: a pricing skill might have SKILL.md with a service-to-tool mapping table, references/pricing-guidance.md with detailed MCP tool usage, and templates/cost-estimate.template.md with the output skeleton.

Step 4: Wire Into Agent Bodies

Add a skill reference in the relevant agent’s .agent.md body:

## MANDATORY: Read Skills First

1. **Read** `.github/skills/my-new-skill/SKILL.md`

That’s the entire wiring. The skill is now connected to the agent. There is no separate registry entry to update — skill wiring is discovered at runtime by tools/scripts/validate-orphaned-content.mjs, which scans agent bodies for Read .github/skills/{name}/SKILL[.digest|.minimal].md references.

Earlier versions of the registry carried a skills (and capability_skills) array on each entry. Those fields were removed in the context-window-optimization pass — they duplicated information already present in agent bodies and made every agent edit a two-file change.

Step 5: Validate

# Check skill format, size, and references
npm run validate:skills

# Check skill body size and cross-references
npm run validate:skill-checks

# Verify agent registry consistency
npm run validate:agent-registry

How Skill Discovery Works

Agents discover skills through description keywords. When a user’s request matches keywords in the skill’s description field (USE FOR / DO NOT USE FOR), VS Code automatically suggests loading that skill. Write descriptions with specific, searchable trigger words.

---

Further Reading

• Core Concepts — the four knowledge layers and how they interact
• Agent Architecture — how agents load and use skills via progressive disclosure
• Workflow Engine & Quality — validators that enforce instruction rules
• MCP Integration — external tool interfaces available to agents
• Validation & Linting — all validation scripts and hooks