Create an Instruction

Build a production-quality instruction file that Copilot auto-applies whenever you edit matching files.

Prerequisites

FrootAI repo cloned
VS Code with GitHub Copilot Chat
Node.js 22+

Step 1: Understand the Frontmatter

Every instruction requires YAML frontmatter:


---
description: "What this instruction enforces (minimum 10 characters)"
applyTo: "**/*.py"
waf:
  - "security"
  - "reliability"
---

Field	Required	Validation
`description`	✅	Minimum 10 characters
`applyTo`	✅	Valid glob pattern
`waf`	No	Valid WAF pillar names

Step 2: Choose Your applyTo Pattern

Pattern	Matches	Use Case
`*/.py`	All Python files	Python coding standards
`*/.{ts,tsx}`	TypeScript + TSX	React/TypeScript standards
`*/.bicep`	All Bicep files	IaC best practices
`solution-plays/01-/*`	Play 01 files only	Per-play targeting
`/infra//*.bicep`	Infra Bicep only	Infrastructure rules

Step 3: Use the Scaffolder


node scripts/scaffold-primitive.js instruction

Follow the prompts:

Name: python-azure-waf
Description: “Python best practices for Azure AI services”
applyTo: **/*.py

Step 4: Write the Body

Include specific, actionable rules with code examples:

instructions/python-azure-waf.instructions.md


---
description: "Enforces Python best practices for Azure AI services — security, reliability, and cost optimization patterns."
applyTo: "**/*.py"
waf:
  - "security"
  - "reliability"
  - "cost-optimization"
---
 
# Python Azure AI Coding Standards
 
## Security
 
- Use `DefaultAzureCredential` for all Azure authentication:
  ```python
  from azure.identity import DefaultAzureCredential
  credential = DefaultAzureCredential()
  ```
- Never hardcode keys or connection strings
 
## Reliability
 
- Add retry with exponential backoff on all Azure SDK calls:
  ```python
  from tenacity import retry, stop_after_attempt, wait_exponential
 
  @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
  async def call_openai(prompt: str) -> str:
      return await client.chat.completions.create(...)
  ```
 
## Cost Optimization
 
- Always set `max_tokens` on LLM calls to prevent budget overruns
- Route by complexity: GPT-4o-mini for classification, GPT-4o for generation

💡

Copilot Follows Examples

Include concrete code patterns. Copilot learns from examples in the instruction body better than from abstract prose.

Step 5: Test in VS Code

Open a .py file (matching your applyTo pattern)
Start a Copilot Chat conversation
Verify suggestions follow your instruction rules
Ask @workspace "What instructions apply to this file?"

Step 6: Validate


npm run validate:primitives

⚠️

Keep Under 200 Lines

Instructions are loaded into the LLM context window. Shorter instructions use fewer tokens and get applied more reliably.

Advanced: Multi-Scope

Target multiple file types:


---
description: "Full-stack WAF standards"
applyTo: "**/*.{ts,tsx,py}"
waf: ["security", "reliability"]
---

Troubleshooting

Problem	Fix
Instruction not applied	Verify glob matches your file
Validator says “description too short”	Expand to 10+ characters
YAML parse error	Add space after colons: `description: "text"`
Copilot ignores rules	Add code examples instead of prose