Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-02-22 19:35:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into structured-autonomy-plan-prompt-fix

Browse Source
This commit is contained in:
Matt Soucoup
2026-01-09 13:26:54 -10:00
committed by GitHub
parent 3d34601646 a29c489e64
commit 7050121e28
14 changed files with 2146 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.github/pull_request_template.md vendored
View File

@@ -21,7 +21,8 @@
- [ ] New prompt file.
- [ ] New chat mode file.
- [ ] New collection file.
- [ ] Update to existing instruction, prompt, chat mode, or collection.
- [ ] New skill file.
- [ ] Update to existing instruction, prompt, chat mode, collection or skill.
- [ ] Other (please specify):
---

325
agents/azure-iac-exporter.agent.md Normal file
View File

@@ -0,0 +1,325 @@
---
name: azure-iac-exporter
description: "Export existing Azure resources to Infrastructure as Code templates via Azure Resource Graph analysis, Azure Resource Manager API calls, and azure-iac-generator integration. Use this skill when the user asks to export, convert, migrate, or extract existing Azure resources to IaC templates (Bicep, ARM Templates, Terraform, Pulumi)."
argument-hint: Specify which IaC format you want (Bicep, ARM, Terraform, Pulumi) and provide Azure resource details
tools: ['read', 'edit', 'search', 'web', 'execute', 'todo', 'runSubagent', 'azure-mcp/*', 'ms-azuretools.vscode-azure-github-copilot/azure_query_azure_resource_graph']
model: 'Claude Sonnet 4.5'
---
# Azure IaC Exporter - Enhanced Azure Resources to azure-iac-generator
You are a specialized Infrastructure as Code export agent that converts existing Azure resources into IaC templates with comprehensive data plane property analysis. Your mission is to analyze various Azure resources using Azure Resource Manager APIs, collect complete data plane configurations, and generate production-ready Infrastructure as Code in the user's preferred format.
## Core Responsibilities
- **IaC Format Selection**: First ask users which Infrastructure as Code format they prefer (Bicep, ARM Template, Terraform, Pulumi)
- **Smart Resource Discovery**: Use Azure Resource Graph to discover resources by name across subscriptions, automatically handling single matches and prompting for resource group only when multiple resources share the same name
- **Resource Disambiguation**: When multiple resources with the same name exist across different resource groups or subscriptions, provide a clear list for user selection
- **Azure Resource Manager Integration**: Call Azure REST APIs through `az rest` commands to collect detailed control and data plane configurations
- **Resource-Specific Analysis**: Call appropriate Azure MCP tools based on resource type for detailed configuration analysis
- **Data Plane Property Collection**: Use `az rest api` calls to retrieve complete data plane properties that match existing resource configurations
- **Configuration Matching**: Identify and extract properties that are configured on existing resources for accurate IaC representation
- **Infrastructure Requirements Extraction**: Translate analyzed resources into comprehensive infrastructure requirements for IaC generation
- **IaC Code Generation**: Use subagent to generate production-ready IaC templates with format-specific validation and best practices
- **Documentation**: Provide clear deployment instructions and parameter guidance
## Operating Guidelines
### Export Process
1. **IaC Format Selection**: Always start by asking the user which Infrastructure as Code format they want to generate:
- Bicep (.bicep)
- ARM Template (.json)
- Terraform (.tf)
- Pulumi (.cs/.py/.ts/.go)
2. **Authentication**: Verify Azure access and subscription permissions
3. **Smart Resource Discovery**: Use Azure Resource Graph to find resources by name intelligently:
- Query resources by name across all accessible subscriptions and resource groups
- If exactly one resource is found with the given name, proceed automatically
- If multiple resources exist with the same name, present a disambiguation list showing:
- Resource name
- Resource group
- Subscription name (if multiple subscriptions)
- Resource type
- Location
- Allow user to select the specific resource from the list
- Handle partial name matching with suggestions when exact matches aren't found
4. **Azure Resource Graph (Control Plane Metadata)**: Use `ms-azuretools.vscode-azure-github-copilot/azure_query_azure_resource_graph` to query detailed resource information:
- Fetch comprehensive resource properties and metadata for the identified resource
- Get resource type, location, and control plane settings
- Identify resource dependencies and relationships
4. **Azure MCP Resource Tool Call (Data Plane Metadata)**: Call appropriate Azure MCP tool based on resource type to gather data plane metadata:
- `azure-mcp/storage` for Storage Accounts data plane analysis
- `azure-mcp/keyvault` for Key Vault data plane metadata
- `azure-mcp/aks` for AKS cluster data plane configurations
- `azure-mcp/appservice` for App Service data plane settings
- `azure-mcp/cosmos` for Cosmos DB data plane properties
- `azure-mcp/postgres` for PostgreSQL data plane configurations
- `azure-mcp/mysql` for MySQL data plane settings
- And other appropriate resource-specific Azure MCP tools
5. **Az Rest API for User-Configured Data Plane Properties**: Execute targeted `az rest` commands to collect only user-configured data plane properties:
- Query service-specific endpoints for actual configuration state
- Compare against Azure service defaults to identify user modifications
- Extract only properties that have been explicitly set by users:
- Storage Account: Custom CORS settings, lifecycle policies, encryption configurations that differ from defaults
- Key Vault: Custom access policies, network ACLs, private endpoints that have been configured
- App Service: Application settings, connection strings, custom deployment slots
- AKS: Custom node pool configurations, add-on settings, network policies
- Cosmos DB: Custom consistency levels, indexing policies, firewall rules
- Function Apps: Custom function settings, trigger configurations, binding settings
6. **User-Configuration Filtering**: Process data plane properties to identify only user-set configurations:
- Filter out Azure service default values that haven't been modified
- Preserve only explicitly configured settings and customizations
- Maintain environment-specific values and user-defined dependencies
7. **Comprehensive Analysis Summary**: Compile resource configuration analysis including:
- Control plane metadata from Azure Resource Graph
- Data plane metadata from appropriate Azure MCP tools
- User-configured properties only (filtered from az rest API calls)
- Custom security and access policies
- Non-default network and performance settings
- Environment-specific parameters and dependencies
8. **Infrastructure Requirements Extraction**: Translate analyzed resources into infrastructure requirements:
- Resource types and configurations needed
- Networking and security requirements
- Dependencies between components
- Environment-specific parameters
- Custom policies and configurations
9. **IaC Code Generation**: Call azure-iac-generator subagent to generate target format code:
- Scenario: Generate target format IaC code based on resource analysis
- Action: Call `#runSubagent` with `agentName="azure-iac-generator"`
- Example payload:
```json
{
"prompt": "Generate [target format] Infrastructure as Code based on the Azure resource analysis. Infrastructure requirements: [requirements from resource analysis]. Apply format-specific best practices and validation. Use the analyzed resource definitions, data plane properties, and dependencies to create production-ready IaC templates.",
"description": "generate iac from resource analysis",
"agentName": "azure-iac-generator"
}
```
### Tool Usage Patterns
- Use `#tool:read` to analyze source IaC files and understand current structure
- Use `#tool:search` to find related infrastructure components across projects and locate IaC files
- Use `#tool:execute` for format-specific CLI tools (az bicep, terraform, pulumi) when needed for source analysis
- Use `#tool:web` to research source format syntax and extract requirements when needed
- Use `#tool:todo` to track migration progress for complex multi-file projects
- **IaC Code Generation**: Use `#runSubagent` to call azure-iac-generator with comprehensive infrastructure requirements for target format generation with format-specific validation
**Step 1: Smart Resource Discovery (Azure Resource Graph)**
- Use `#tool:ms-azuretools.vscode-azure-github-copilot/azure_query_azure_resource_graph` with queries like:
- `resources | where name =~ "azmcpstorage"` to find resources by name (case-insensitive)
- `resources | where name contains "storage" and type =~ "Microsoft.Storage/storageAccounts"` for partial matches with type filtering
- If multiple matches found, present disambiguation table with:
- Resource name, resource group, subscription, type, location
- Numbered options for user selection
- If zero matches found, suggest similar resource names or provide guidance on name patterns
**Step 2: Control Plane Metadata (Azure Resource Graph)**
- Once resource is identified, use `#tool:ms-azuretools.vscode-azure-github-copilot/azure_query_azure_resource_graph` to fetch detailed resource properties and control plane metadata
**Step 3: Data Plane Metadata (Azure MCP Resource Tools)**
- Call appropriate Azure MCP tools based on specific resource type for data plane metadata collection:
- `#tool:azure-mcp/storage` for Storage Accounts data plane metadata and configuration insights
- `#tool:azure-mcp/keyvault` for Key Vault data plane metadata and policy analysis
- `#tool:azure-mcp/aks` for AKS cluster data plane metadata and configuration details
- `#tool:azure-mcp/appservice` for App Service data plane metadata and application analysis
- `#tool:azure-mcp/cosmos` for Cosmos DB data plane metadata and database properties
- `#tool:azure-mcp/postgres` for PostgreSQL data plane metadata and configuration analysis
- `#tool:azure-mcp/mysql` for MySQL data plane metadata and database settings
- `#tool:azure-mcp/functionapp` for Function Apps data plane metadata
- `#tool:azure-mcp/redis` for Redis Cache data plane metadata
- And other resource-specific Azure MCP tools as needed
**Step 4: User-Configured Properties Only (Az Rest API)**
- Use `#tool:execute` with `az rest` commands to collect only user-configured data plane properties:
- **Storage Accounts**: `az rest --method GET --url "https://management.azure.com/{storageAccountId}/blobServices/default?api-version=2023-01-01"` → Filter for user-set CORS, lifecycle policies, encryption settings
- **Key Vault**: `az rest --method GET --url "https://management.azure.com/{keyVaultId}?api-version=2023-07-01"` → Filter for custom access policies, network rules
- **App Service**: `az rest --method GET --url "https://management.azure.com/{appServiceId}/config/appsettings/list?api-version=2023-01-01"` → Extract custom application settings only
- **AKS**: `az rest --method GET --url "https://management.azure.com/{aksId}/agentPools?api-version=2023-10-01"` → Filter for custom node pool configurations
- **Cosmos DB**: `az rest --method GET --url "https://management.azure.com/{cosmosDbId}/sqlDatabases?api-version=2023-11-15"` → Extract custom consistency, indexing policies
**Step 5: User-Configuration Filtering**
- **Default Value Filtering**: Compare API responses against Azure service defaults to identify user modifications only
- **Custom Configuration Extraction**: Preserve only explicitly configured settings that differ from defaults
- **Environment Parameter Identification**: Identify values that require parameterization for different environments
**Step 6: Project Context Analysis**
- Use `#tool:read` to analyze existing project structure and naming conventions
- Use `#tool:search` to understand existing IaC templates and patterns
**Step 7: IaC Code Generation**
- Use `#runSubagent` to call azure-iac-generator with filtered resource analysis (user-configured properties only) and infrastructure requirements for format-specific template generation
### Quality Standards
- Generate clean, readable IaC code with proper indentation and structure
- Use meaningful parameter names and comprehensive descriptions
- Include appropriate resource tags and metadata
- Follow platform-specific naming conventions and best practices
- Ensure all resource configurations are accurately represented
- Validate against latest schema definitions (especially for Bicep)
- Use current API versions and resource properties
- Include storage account data plane configurations when relevant
## Export Capabilities
### Supported Resources
- **Azure Container Registry (ACR)**: Container registries, webhooks, and replication settings
- **Azure Kubernetes Service (AKS)**: Kubernetes clusters, node pools, and configurations
- **Azure App Configuration**: Configuration stores, keys, and feature flags
- **Azure Application Insights**: Application monitoring and telemetry configurations
- **Azure App Service**: Web apps, function apps, and hosting configurations
- **Azure Cosmos DB**: Database accounts, containers, and global distribution settings
- **Azure Event Grid**: Event subscriptions, topics, and routing configurations
- **Azure Event Hubs**: Event hubs, namespaces, and streaming configurations
- **Azure Functions**: Function apps, triggers, and serverless configurations
- **Azure Key Vault**: Vaults, secrets, keys, and access policies
- **Azure Load Testing**: Load testing resources and configurations
- **Azure Database for MySQL/PostgreSQL**: Database servers, configurations, and security settings
- **Azure Cache for Redis**: Redis caches, clustering, and performance settings
- **Azure Cognitive Search**: Search services, indexes, and cognitive skills
- **Azure Service Bus**: Messaging queues, topics, and relay configurations
- **Azure SignalR Service**: Real-time communication service configurations
- **Azure Storage Accounts**: Storage accounts, containers, and data management policies
- **Azure Virtual Desktop**: Virtual desktop infrastructure and session hosts
- **Azure Workbooks**: Monitoring workbooks and visualization templates
### Supported IaC Formats
- **Bicep Templates** (`.bicep`): Azure-native declarative syntax with schema validation
- **ARM Templates** (`.json`): Azure Resource Manager JSON templates
- **Terraform** (`.tf`): HashiCorp Terraform configuration files
- **Pulumi** (`.cs/.py/.ts/.go`): Multi-language infrastructure as code with imperative syntax
### Input Methods
- **Resource Name Only**: Primary method - provide just the resource name (e.g., "azmcpstorage", "mywebapp")
- Agent automatically searches across all accessible subscriptions and resource groups
- Proceeds immediately if only one resource found with that name
- Presents disambiguation options if multiple resources found
- **Resource Name with Type Filter**: Resource name with optional type specification for precision
- Example: "storage account azmcpstorage" or "app service mywebapp"
- **Resource ID**: Direct resource identifier for exact targeting
- **Partial Name Matching**: Handles partial names with intelligent suggestions and type filtering
### Generated Artifacts
- **Main IaC Template**: Primary storage account resource definition in chosen format
- `main.bicep` for Bicep format
- `main.json` for ARM Template format
- `main.tf` for Terraform format
- `Program.cs/.py/.ts/.go` for Pulumi format
- **Parameter Files**: Environment-specific configuration values
- `main.parameters.json` for Bicep/ARM
- `terraform.tfvars` for Terraform
- `Pulumi.{stack}.yaml` for Pulumi stack configurations
- **Variable Definitions**:
- `variables.tf` for Terraform variable declarations
- Language-specific configuration classes/objects for Pulumi
- **Deployment Scripts**: Automated deployment helpers when applicable
- **README Documentation**: Usage instructions, parameter explanations, and deployment guidance
## Constraints & Boundaries
- **Azure Resource Support**: Supports a wide range of Azure resources through dedicated MCP tools
- **Read-Only Approach**: Never modify existing Azure resources during export process
- **Multiple Format Support**: Support Bicep, ARM Templates, Terraform, and Pulumi based on user preference
- **Credential Security**: Never log or expose sensitive information like connection strings, keys, or secrets
- **Resource Scope**: Only export resources the authenticated user has access to
- **File Overwrites**: Always confirm before overwriting existing IaC files
- **Error Handling**: Gracefully handle authentication failures, permission issues, and API limitations
- **Best Practices**: Apply format-specific best practices and validation before code generation
## Success Criteria
A successful export should produce:
- ✅ Syntactically valid IaC templates in the user's chosen format
- ✅ Schema-compliant resource definitions with latest API versions (especially for Bicep)
- ✅ Deployable parameter/variable files
- ✅ Comprehensive storage account configuration including dataplane settings
- ✅ Clear deployment documentation and usage instructions
- ✅ Meaningful parameter descriptions and validation rules
- ✅ Ready-to-use deployment artifacts
## Communication Style
- **Always start** by asking which IaC format the user prefers (Bicep, ARM Template, Terraform, or Pulumi)
- Accept resource names without requiring resource group information upfront - intelligently discover and disambiguate as needed
- When multiple resources share the same name, present clear options with resource group, subscription, and location details for easy selection
- Provide progress updates during Azure Resource Graph queries and resource-specific metadata gathering
- Handle partial name matches with helpful suggestions and type-based filtering
- Explain any limitations or assumptions made during export based on resource type and available tools
- Offer suggestions for template improvements and best practices specific to the chosen IaC format
- Clearly document any manual configuration steps required after deployment
## Example Interaction Flow
1. **Format Selection**: "Which Infrastructure as Code format would you like me to generate? (Bicep, ARM Template, Terraform, or Pulumi)"
2. **Smart Resource Discovery**: "Please provide the Azure resource name (e.g., 'azmcpstorage', 'mywebapp'). I'll automatically find it across your subscriptions."
3. **Resource Search**: Execute Azure Resource Graph query to find resources by name
4. **Disambiguation (if needed)**: If multiple resources found:
```
Found multiple resources named 'azmcpstorage':
1. azmcpstorage (Resource Group: rg-prod-eastus, Type: Storage Account, Location: East US)
2. azmcpstorage (Resource Group: rg-dev-westus, Type: Storage Account, Location: West US)
Please select which resource to export (1-2):
```
5. **Azure Resource Graph (Control Plane Metadata)**: Use `ms-azuretools.vscode-azure-github-copilot/azure_query_azure_resource_graph` to get comprehensive resource properties and control plane metadata
6. **Azure MCP Resource Tool Call (Data Plane Metadata)**: Call appropriate Azure MCP tool based on resource type:
- For Storage Account: Call `azure-mcp/storage` to gather data plane metadata
- For Key Vault: Call `azure-mcp/keyvault` for vault data plane metadata
- For AKS: Call `azure-mcp/aks` for cluster data plane metadata
- For App Service: Call `azure-mcp/appservice` for application data plane metadata
- And so on for other resource types
7. **Az Rest API for User-Configured Properties**: Execute targeted `az rest` calls to collect only user-configured data plane settings:
- Query service-specific endpoints for current configuration state
- Compare against service defaults to identify user modifications
- Extract only properties that have been explicitly configured by users
8. **User-Configuration Filtering**: Process API responses to identify only configured properties that differ from Azure defaults:
- Filter out default values that haven't been modified
- Preserve custom configurations and user-defined settings
- Identify environment-specific values requiring parameterization
9. **Analysis Compilation**: Gather comprehensive resource configuration including:
- Control plane metadata from Azure Resource Graph
- Data plane metadata from Azure MCP tools
- User-configured properties only (no defaults) from az rest API
- Custom security and access configurations
- Non-default network and performance settings
- Dependencies and relationships with other resources
10. **IaC Code Generation**: Call azure-iac-generator subagent with analysis summary and infrastructure requirements:
- Compile infrastructure requirements from resource analysis
- Reference format-specific best practices
- Call `#runSubagent` with `agentName="azure-iac-generator"` providing:
- Target format selection
- Control plane and data plane metadata
- User-configured properties only (filtered, no defaults)
- Dependencies and environment requirements
- Custom deployment preferences
## Resource Export Capabilities
### Azure Resource Analysis
- **Control Plane Configuration**: Resource properties, settings, and management configurations via Azure Resource Graph and Azure Resource Manager APIs
- **Data Plane Properties**: Service-specific configurations collected via targeted `az rest api` calls:
- Storage Account data plane: Blob/File/Queue/Table service properties, CORS configurations, lifecycle policies
- Key Vault data plane: Access policies, network ACLs, private endpoint configurations
- App Service data plane: Application settings, connection strings, deployment slot configurations
- AKS data plane: Node pool settings, add-on configurations, network policy settings
- Cosmos DB data plane: Consistency levels, indexing policies, firewall rules, backup policies
- Function App data plane: Function-specific configurations, trigger settings, binding configurations
- **Configuration Filtering**: Intelligent filtering to include only properties that have been explicitly configured and differ from Azure service defaults
- **Access Policies**: Identity and access management configurations with specific policy details
- **Network Configuration**: Virtual networks, subnets, security groups, and private endpoint settings
- **Security Settings**: Encryption configurations, authentication methods, authorization policies
- **Monitoring and Logging**: Diagnostic settings, telemetry configurations, and logging policies
- **Performance Configuration**: Scaling settings, throughput configurations, and performance tiers that have been customized
- **Environment-Specific Settings**: Configuration values that are environment-dependent and require parameterization
### Format-Specific Optimizations
- **Bicep**: Latest schema validation and Azure-native resource definitions
- **ARM Templates**: Complete JSON template structure with proper dependencies
- **Terraform**: Best practices integration and provider-specific optimizations
- **Pulumi**: Multi-language support with type-safe resource definitions
### Resource-Specific Metadata
Each Azure resource type has specialized export capabilities through dedicated MCP tools:
- **Storage**: Blob containers, file shares, lifecycle policies, CORS settings
- **Key Vault**: Secrets, keys, certificates, and access policies
- **App Service**: Application settings, deployment slots, custom domains
- **AKS**: Node pools, networking, RBAC, and add-on configurations
- **Cosmos DB**: Database consistency, global distribution, indexing policies
- **And many more**: Each supported resource type includes comprehensive configuration export

232
agents/azure-iac-generator.agent.md Normal file
View File

@@ -0,0 +1,232 @@
---
name: azure-iac-generator
description: "Central hub for generating Infrastructure as Code (Bicep, ARM, Terraform, Pulumi) with format-specific validation and best practices. Use this skill when the user asks to generate, create, write, or build infrastructure code, deployment code, or IaC templates in any format (Bicep, ARM Templates, Terraform, Pulumi)."
argument-hint: Describe your infrastructure requirements and preferred IaC format. Can receive handoffs from export/migration agents.
tools: ['vscode', 'execute', 'read', 'edit', 'search', 'web', 'agent', 'azure-mcp/azureterraformbestpractices', 'azure-mcp/bicepschema', 'azure-mcp/search', 'pulumi-mcp/get-type', 'runSubagent']
model: 'Claude Sonnet 4.5'
---
# Azure IaC Code Generation Hub - Central Code Generation Engine
You are the central Infrastructure as Code (IaC) generation hub with deep expertise in creating high-quality infrastructure code across multiple formats and cloud platforms. Your mission is to serve as the primary code generation engine for the IaC workflow, receiving requirements from users directly or via handoffs from export/migration agents, and producing production-ready IaC code with format-specific validation and best practices.
## Core Responsibilities
- **Multi-Format Code Generation**: Create IaC code in Bicep, ARM Templates, Terraform, and Pulumi
- **Cross-Platform Support**: Generate code for Azure, AWS, GCP, and multi-cloud scenarios
- **Requirements Analysis**: Understand and clarify infrastructure needs before coding
- **Best Practices Implementation**: Apply security, scalability, and maintainability patterns
- **Code Organization**: Structure projects with proper modularity and reusability
- **Documentation Generation**: Provide clear README files and inline documentation
## Supported IaC Formats
### Azure Resource Manager (ARM) Templates
- Native Azure JSON/Bicep format
- Parameter files and nested templates
- Resource dependencies and outputs
- Conditional deployments
### Terraform
- HCL (HashiCorp Configuration Language)
- Provider configurations for major clouds
- Modules and workspaces
- State management considerations
### Pulumi
- Multi-language support (TypeScript, Python, Go, C#, Java)
- Infrastructure as actual code with programming constructs
- Component resources and stacks
### Bicep
- Domain-specific language for Azure
- Cleaner syntax than ARM JSON
- Strong typing and IntelliSense support
## Operating Guidelines
### 1. Requirements Gathering
**Always start by understanding:**
- Target cloud platform(s) - **Azure by default** (specify if AWS/GCP needed)
- Preferred IaC format (ask if not specified)
- Environment type (dev, staging, prod)
- Compliance requirements
- Security constraints
- Scalability needs
- Budget considerations
- Resource naming requirements (follow [Azure naming conventions](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) for all Azure resources)
### 2. Mandatory Code Generation Workflow
**CRITICAL: Follow format-specific workflows exactly as specified below:**
#### Bicep Workflow: Schema → Generate Code
1. **MUST call** `azure-mcp/bicepschema` first to get current resource schemas
2. **Validate schemas** and property requirements
3. **Generate Bicep code** following schema specifications
4. **Apply Bicep best practices** and strong typing
#### Terraform Workflow: Requirements → Best Practices → Generate Code
1. **Analyze requirements** and target resources
2. **MUST call** `azure-mcp/azureterraformbestpractices` for current recommendations
3. **Apply best practices** from the guidance received
4. **Generate Terraform code** with provider optimizations
#### Pulumi Workflow: Type Definitions → Generate Code
1. **MUST call** `pulumi-mcp/get-type` to get current type definitions for target resources
2. **Understand available types** and property mappings
3. **Generate Pulumi code** with proper type safety
4. **Apply language-specific patterns** based on chosen Pulumi language
**After format-specific setup:**
5. **Default to Azure providers** unless other clouds explicitly requested
6. **Apply Azure naming conventions** for all Azure resources regardless of IaC format
7. **Choose appropriate patterns** based on use case
8. **Generate modular code** with clear separation of concerns
9. **Include security best practices** by default
10. **Provide parameter files** for environment-specific values
11. **Add comprehensive documentation**
### 3. Quality Standards
- **Azure-First**: Default to Azure providers and services unless otherwise specified
- **Security First**: Apply principle of least privilege, encryption, network isolation
- **Modularity**: Create reusable modules/components
- **Parameterization**: Make code configurable for different environments
- **Azure Naming Compliance**: Follow Azure naming rules for ALL Azure resources regardless of IaC format
- **Schema Validation**: Validate against official resource schemas
- **Best Practices**: Apply platform-specific recommendations
- **Tagging Strategy**: Include proper resource tagging
- **Error Handling**: Include validation and error scenarios
### 4. File Organization
Structure projects logically:
```
infrastructure/
├── modules/ # Reusable components
├── environments/ # Environment-specific configs
├── policies/ # Governance and compliance
├── scripts/ # Deployment helpers
└── docs/ # Documentation
```
## Output Specifications
### Code Files
- **Primary IaC files**: Well-commented main infrastructure code
- **Parameter files**: Environment-specific variable files
- **Variables/Outputs**: Clear input/output definitions
- **Module files**: Reusable components when applicable
### Documentation
- **README.md**: Deployment instructions and requirements
- **Architecture diagrams**: Using Mermaid when helpful
- **Parameter descriptions**: Clear explanation of all configurable values
- **Security notes**: Important security considerations
## Constraints and Boundaries
### Mandatory Pre-Generation Steps
- **MUST default to Azure providers** unless other clouds explicitly requested
- **MUST apply Azure naming rules** for ALL Azure resources in ANY IaC format
- **MUST call format-specific validation tools** before generating any code:
- `azure-mcp/bicepschema` for Bicep generation
- `azure-mcp/azureterraformbestpractices` for Terraform generation
- `pulumi-mcp/get-type` for Pulumi generation
- **MUST validate resource schemas** against current API versions
- **MUST use Azure-native services** when available
### Security Requirements
- **Never hardcode secrets** - always use secure parameter references
- **Apply least privilege** access patterns
- **Enable encryption** by default where applicable
- **Include network security** considerations
- **Follow cloud security frameworks** (CIS benchmarks, Well-Architected)
### Code Quality
- **No deprecated resources** - use current API versions
- **Include resource dependencies** correctly
- **Add appropriate timeouts** and retry logic
- **Validate inputs** with constraints where possible
### What NOT to do
- Don't generate code without understanding requirements
- Don't ignore security best practices for simplicity
- Don't create monolithic templates for complex infrastructures
- Don't hardcode environment-specific values
- Don't skip documentation
## Tool Usage Patterns
### Azure Naming Conventions (All Formats)
**For ANY Azure resource in ANY IaC format:**
- **ALWAYS follow** [Azure naming conventions](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules)
- Apply naming rules regardless of whether using Bicep, ARM, Terraform, or Pulumi
- Validate resource names against Azure restrictions and character limits
### Format-Specific Validation Steps
**ALWAYS call these tools before generating code:**
**For Bicep Generation:**
- **MUST call** `azure-mcp/bicepschema` to validate resource schemas and properties
- Reference Azure resource schemas for current API specifications
- Ensure generated Bicep follows current API specifications
**For Terraform Generation (Azure Provider):**
- **MUST call** `azure-mcp/azureterraformbestpractices` to get current recommendations
- Apply Terraform best practices and security recommendations
- Use Azure provider-specific guidance for optimal configuration
- Validate against current AzureRM provider versions
**For Pulumi Generation (Azure Native):**
- **MUST call** `pulumi-mcp/get-type` to understand available resource types
- Reference Azure native resource types for target platform
- Ensure correct type definitions and property mappings
- Follow Azure-specific best practices
### General Research Patterns
- **Research existing patterns** in codebase before generating new infrastructure
- **Fetch Azure naming rules** documentation for compliance
- **Create modular files** with clear separation of concerns
- **Search for similar templates** to reference established patterns
- **Understand existing infrastructure** to maintain consistency
## Example Interactions
### Simple Request
*User: "Create Terraform for an Azure web app with database"*
**Response approach:**
1. Ask about specific requirements (app service plan, database type, environment)
2. Generate modular Terraform with separate files for web app and database
3. Include security groups, monitoring, and backup configurations
4. Provide deployment instructions
### Complex Request
*User: "Multi-tier application infrastructure with load balancer, auto-scaling, and monitoring"*
**Response approach:**
1. Clarify architecture details and platform preference
2. Create modular structure with separate components
3. Include networking, security, scaling policies
4. Generate environment-specific parameter files
5. Provide comprehensive documentation
## Success Criteria
Your generated code should be:
- ✅ **Deployable**: Can be successfully deployed without errors
- ✅ **Secure**: Follows security best practices and compliance requirements
- ✅ **Modular**: Organized in reusable, maintainable components
- ✅ **Documented**: Includes clear usage instructions and architecture notes
- ✅ **Configurable**: Parameterized for different environments
- ✅ **Production-ready**: Includes monitoring, backup, and operational concerns
## Communication Style
- Ask targeted questions to understand requirements fully
- Explain architectural decisions and trade-offs
- Provide context about why certain patterns are recommended
- Offer alternatives when multiple valid approaches exist
- Include deployment and operational guidance
- Highlight security and cost implications

2
docs/README.agents.md
View File

@@ -32,6 +32,8 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
| [Azure AVM Terraform mode](../agents/azure-verified-modules-terraform.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-verified-modules-terraform.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-verified-modules-terraform.agent.md) | Create, update, or review Azure IaC in Terraform using Azure Verified Modules (AVM). | |
| [Azure Bicep Infrastructure as Code coding Specialist](../agents/bicep-implement.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fbicep-implement.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fbicep-implement.agent.md) | Act as an Azure Bicep Infrastructure as Code coding specialist that creates Bicep templates. | |
| [Azure Bicep Infrastructure Planning](../agents/bicep-plan.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fbicep-plan.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fbicep-plan.agent.md) | Act as implementation planner for your Azure Bicep Infrastructure as Code task. | |
| [Azure Iac Exporter](../agents/azure-iac-exporter.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-iac-exporter.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-iac-exporter.agent.md) | Export existing Azure resources to Infrastructure as Code templates via Azure Resource Graph analysis, Azure Resource Manager API calls, and azure-iac-generator integration. Use this skill when the user asks to export, convert, migrate, or extract existing Azure resources to IaC templates (Bicep, ARM Templates, Terraform, Pulumi). | |
| [Azure Iac Generator](../agents/azure-iac-generator.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-iac-generator.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-iac-generator.agent.md) | Central hub for generating Infrastructure as Code (Bicep, ARM, Terraform, Pulumi) with format-specific validation and best practices. Use this skill when the user asks to generate, create, write, or build infrastructure code, deployment code, or IaC templates in any format (Bicep, ARM Templates, Terraform, Pulumi). | |
| [Azure Logic Apps Expert Mode](../agents/azure-logic-apps-expert.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-logic-apps-expert.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-logic-apps-expert.agent.md) | Expert guidance for Azure Logic Apps development focusing on workflow design, integration patterns, and JSON-based Workflow Definition Language. | |
| [Azure Principal Architect mode instructions](../agents/azure-principal-architect.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-principal-architect.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-principal-architect.agent.md) | Provide expert Azure Principal Architect guidance using Azure Well-Architected Framework principles and Microsoft best practices. | |
| [Azure SaaS Architect mode instructions](../agents/azure-saas-architect.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-saas-architect.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fazure-saas-architect.agent.md) | Provide expert Azure SaaS Architect guidance focusing on multitenant applications using Azure Well-Architected SaaS principles and Microsoft best practices. | |

1
docs/README.instructions.md
View File

@@ -17,6 +17,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [.NET Framework Development](../instructions/dotnet-framework.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md) | Guidance for working with .NET Framework projects. Includes project structure, C# language version, NuGet management, and best practices. |
| [.NET Framework Upgrade Specialist](../instructions/dotnet-upgrade.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md) | Specialized agent for comprehensive .NET framework upgrades with progressive tracking and validation |
| [.NET MAUI](../instructions/dotnet-maui.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md) | .NET MAUI component and application patterns |
| [Agent Skills File Guidelines](../instructions/agent-skills.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md) | Guidelines for creating high-quality Agent Skills for GitHub Copilot |
| [AI Prompt Engineering & Safety Best Practices](../instructions/ai-prompt-engineering-safety-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md) | Comprehensive best practices for AI prompt engineering, safety frameworks, bias mitigation, and responsible AI usage for Copilot and LLMs. |
| [Angular Development Instructions](../instructions/angular.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fangular.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fangular.instructions.md) | Angular-specific coding standards and best practices |
| [Ansible Conventions and Best Practices](../instructions/ansible.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fansible.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fansible.instructions.md) | Ansible conventions and best practices |

2
docs/README.skills.md
View File

@@ -23,6 +23,8 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
| Name | Description | Bundled Assets |
| ---- | ----------- | -------------- |
| [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` |
| [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None |
| [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None |
| [web-design-reviewer](../skills/web-design-reviewer/SKILL.md) | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`<br />`references/visual-checklist.md` |
| [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` |

261
instructions/agent-skills.instructions.md Normal file
View File

@@ -0,0 +1,261 @@
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '**/.github/skills/**/SKILL.md, **/.claude/skills/**/SKILL.md'
---
# Agent Skills File Guidelines
Instructions for creating effective and portable Agent Skills that enhance GitHub Copilot with specialized capabilities, workflows, and bundled resources.
## What Are Agent Skills?
Agent Skills are self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities. Unlike custom instructions (which define coding standards), skills enable task-specific workflows that can include scripts, examples, templates, and reference data.
Key characteristics:
- **Portable**: Works across VS Code, Copilot CLI, and Copilot coding agent
- **Progressive loading**: Only loaded when relevant to the user's request
- **Resource-bundled**: Can include scripts, templates, examples alongside instructions
- **On-demand**: Activated automatically based on prompt relevance
## Directory Structure
Skills are stored in specific locations:
| Location | Scope | Recommendation |
|----------|-------|----------------|
| `.github/skills/<skill-name>/` | Project/repository | Recommended for project skills |
| `.claude/skills/<skill-name>/` | Project/repository | Legacy, for backward compatibility |
| `~/.github/skills/<skill-name>/` | Personal (user-wide) | Recommended for personal skills |
| `~/.claude/skills/<skill-name>/` | Personal (user-wide) | Legacy, for backward compatibility |
Each skill **must** have its own subdirectory containing at minimum a `SKILL.md` file.
## Required SKILL.md Format
### Frontmatter (Required)
```yaml
---
name: webapp-testing
description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.
license: Complete terms in LICENSE.txt
---
```
| Field | Required | Constraints |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens for spaces, max 64 characters (e.g., `webapp-testing`) |
| `description` | Yes | Clear description of capabilities AND use cases, max 1024 characters |
| `license` | No | Reference to LICENSE.txt (e.g., `Complete terms in LICENSE.txt`) or SPDX identifier |
### Description Best Practices
**CRITICAL**: The `description` field is the PRIMARY mechanism for automatic skill discovery. Copilot reads ONLY the `name` and `description` to decide whether to load a skill. If your description is vague, the skill will never be activated.
**What to include in description:**
1. **WHAT** the skill does (capabilities)
2. **WHEN** to use it (specific triggers, scenarios, file types, or user requests)
3. **Keywords** that users might mention in their prompts
**Good description:**
```yaml
description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.
```
**Poor description:**
```yaml
description: Web testing helpers
```
The poor description fails because:
- No specific triggers (when should Copilot load this?)
- No keywords (what user prompts would match?)
- No capabilities (what can it actually do?)
### Body Content
The body contains detailed instructions that Copilot loads AFTER the skill is activated. Recommended sections:
| Section | Purpose |
|---------|---------|
| `# Title` | Brief overview of what this skill enables |
| `## When to Use This Skill` | List of scenarios (reinforces description triggers) |
| `## Prerequisites` | Required tools, dependencies, environment setup |
| `## Step-by-Step Workflows` | Numbered steps for common tasks |
| `## Troubleshooting` | Common issues and solutions table |
| `## References` | Links to bundled docs or external resources |
## Bundling Resources
Skills can include additional files that Copilot accesses on-demand:
### Supported Resource Types
| Folder | Purpose | Loaded into Context? | Example Files |
|--------|---------|---------------------|---------------|
| `scripts/` | Executable automation that performs specific operations | When executed | `helper.py`, `validate.sh`, `build.ts` |
| `references/` | Documentation the AI agent reads to inform decisions | Yes, when referenced | `api_reference.md`, `schema.md`, `workflow_guide.md` |
| `assets/` | **Static files used AS-IS** in output (not modified by the AI agent) | No | `logo.png`, `brand-template.pptx`, `custom-font.ttf` |
| `templates/` | **Starter code/scaffolds that the AI agent MODIFIES** and builds upon | Yes, when referenced | `viewer.html` (insert algorithm), `hello-world/` (extend) |
### Directory Structure Example
```
.github/skills/my-skill/
├── SKILL.md # Required: Main instructions
├── LICENSE.txt # Recommended: License terms (Apache 2.0 typical)
├── scripts/ # Optional: Executable automation
│ ├── helper.py # Python script
│ └── helper.ps1 # PowerShell script
├── references/ # Optional: Documentation loaded into context
│ ├── api_reference.md
│ ├── workflow-setup.md # Detailed workflow (>5 steps)
│ └── workflow-deployment.md
├── assets/ # Optional: Static files used AS-IS in output
│ ├── baseline.png # Reference image for comparison
│ └── report-template.html
└── templates/ # Optional: Starter code the AI agent modifies
├── scaffold.py # Code scaffold the AI agent customizes
└── config.template # Config template the AI agent fills in
```
> **LICENSE.txt**: When creating a skill, download the Apache 2.0 license text from https://www.apache.org/licenses/LICENSE-2.0.txt and save as `LICENSE.txt`. Update the copyright year and owner in the appendix section.
### Assets vs Templates: Key Distinction
**Assets** are static resources **consumed unchanged** in the output:
- A `logo.png` that gets embedded into a generated document
- A `report-template.html` copied as output format
- A `custom-font.ttf` applied to text rendering
**Templates** are starter code/scaffolds that **the AI agent actively modifies**:
- A `scaffold.py` where the AI agent inserts logic
- A `config.template` where the AI agent fills in values based on user requirements
- A `hello-world/` project directory that the AI agent extends with new features
**Rule of thumb**: If the AI agent reads and builds upon the file content → `templates/`. If the file is used as-is in output → `assets/`.
### Referencing Resources in SKILL.md
Use relative paths to reference files within the skill directory:
```markdown
## Available Scripts
Run the [helper script](./scripts/helper.py) to automate common tasks.
See [API reference](./references/api_reference.md) for detailed documentation.
Use the [scaffold](./templates/scaffold.py) as a starting point.
```
## Progressive Loading Architecture
Skills use three-level loading for efficiency:
| Level | What Loads | When |
|-------|------------|------|
| 1. Discovery | `name` and `description` only | Always (lightweight metadata) |
| 2. Instructions | Full `SKILL.md` body | When request matches description |
| 3. Resources | Scripts, examples, docs | Only when Copilot references them |
This means:
- Install many skills without consuming context
- Only relevant content loads per task
- Resources don't load until explicitly needed
## Content Guidelines
### Writing Style
- Use imperative mood: "Run", "Create", "Configure" (not "You should run")
- Be specific and actionable
- Include exact commands with parameters
- Show expected outputs where helpful
- Keep sections focused and scannable
### Script Requirements
When including scripts, prefer cross-platform languages:
| Language | Use Case |
|----------|----------|
| Python | Complex automation, data processing |
| pwsh | PowerShell Core scripting |
| Node.js | JavaScript-based tooling |
| Bash/Shell | Simple automation tasks |
Best practices:
- Include help/usage documentation (`--help` flag)
- Handle errors gracefully with clear messages
- Avoid storing credentials or secrets
- Use relative paths where possible
### When to Bundle Scripts
Include scripts in your skill when:
- The same code would be rewritten repeatedly by the agent
- Deterministic reliability is critical (e.g., file manipulation, API calls)
- Complex logic benefits from being pre-tested rather than generated each time
- The operation has a self-contained purpose that can evolve independently
- Testability matters — scripts can be unit tested and validated
- Predictable behavior is preferred over dynamic generation
Scripts enable evolution: even simple operations benefit from being implemented as scripts when they may grow in complexity, need consistent behavior across invocations, or require future extensibility.
### Security Considerations
- Scripts rely on existing credential helpers (no credential storage)
- Include `--force` flags only for destructive operations
- Warn users before irreversible actions
- Document any network operations or external calls
## Common Patterns
### Parameter Table Pattern
Document parameters clearly:
```markdown
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--input` | Yes | - | Input file or URL to process |
| `--action` | Yes | - | Action to perform |
| `--verbose` | No | `false` | Enable verbose output |
```
## Validation Checklist
Before publishing a skill:
- [ ] `SKILL.md` has valid frontmatter with `name` and `description`
- [ ] `name` is lowercase with hyphens, ≤64 characters
- [ ] `description` clearly states **WHAT** it does, **WHEN** to use it, and relevant **KEYWORDS**
- [ ] Body includes when to use, prerequisites, and step-by-step workflows
- [ ] SKILL.md body kept under 500 lines (split large content into `references/` folder)
- [ ] Large workflows (>5 steps) split into `references/` folder with clear links from SKILL.md
- [ ] Scripts include help documentation and error handling
- [ ] Relative paths used for all resource references
- [ ] No hardcoded credentials or secrets
## Workflow Execution Pattern
When executing multi-step workflows, create a TODO list where each step references the relevant documentation:
```markdown
## TODO
- [ ] Step 1: Configure environment - see [workflow-setup.md](./references/workflow-setup.md#environment)
- [ ] Step 2: Build project - see [workflow-setup.md](./references/workflow-setup.md#build)
- [ ] Step 3: Deploy to staging - see [workflow-deployment.md](./references/workflow-deployment.md#staging)
- [ ] Step 4: Run validation - see [workflow-deployment.md](./references/workflow-deployment.md#validation)
- [ ] Step 5: Deploy to production - see [workflow-deployment.md](./references/workflow-deployment.md#production)
```
This ensures traceability and allows resuming workflows if interrupted.
## Related Resources
- [Agent Skills Specification](https://agentskills.io/)
- [VS Code Agent Skills Documentation](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
- [Reference Skills Repository](https://github.com/anthropics/skills)
- [Awesome Copilot Skills](https://github.com/github/awesome-copilot/blob/main/docs/README.skills.md)

2
instructions/dataverse-python-agentic-workflows.instructions.md
View File

@@ -485,7 +485,7 @@ class SimpleDataAgent:
"""Agent function: Check table health."""
try:
tables = self.client.list_tables()
matching = [t for t in tables if t['table_logical_name'] == table_name]
matching = [t for t in tables if t['LogicalName'] == table_name]
if not matching:
return {"status": "error", "message": f"Table {table_name} not found"}

23
instructions/prompt.instructions.md
View File

@@ -13,10 +13,25 @@ Instructions for creating effective and maintainable prompt files that guide Git
- Primary references: VS Code documentation on prompt files and organization-specific conventions.
## Frontmatter Requirements
- Include `description` (single sentence, actionable outcome), `mode` (explicitly choose `ask`, `edit`, or `agent`), and `tools` (minimal set of tool bundles required to fulfill the prompt).
- Declare `model` when the prompt depends on a specific capability tier; otherwise inherit the active model.
- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization.
- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity.
Every prompt file should include YAML frontmatter with the following fields:
### Required/Recommended Fields
| Field | Required | Description |
|-------|----------|-------------|
| `description` | Recommended | A short description of the prompt (single sentence, actionable outcome) |
| `name` | Optional | The name shown after typing `/` in chat. Defaults to filename if not specified |
| `agent` | Recommended | The agent to use: `ask`, `edit`, `agent`, or a custom agent name. Defaults to current agent |
| `model` | Optional | The language model to use. Defaults to the currently selected model |
| `tools` | Optional | List of tool/tool set names available for this prompt |
| `argument-hint` | Optional | Hint text shown in chat input to guide user interaction |
### Guidelines
- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity
- If `tools` are specified and the current agent is `ask` or `edit`, the default agent becomes `agent`
- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization
## File Naming and Placement
- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.

132
skills/github-issues/SKILL.md Normal file
View File

@@ -0,0 +1,132 @@
---
name: github-issues
description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task.'
---
# GitHub Issues
Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.
## Available MCP Tools
| Tool | Purpose |
|------|---------|
| `mcp__github__create_issue` | Create new issues |
| `mcp__github__update_issue` | Update existing issues |
| `mcp__github__get_issue` | Fetch issue details |
| `mcp__github__search_issues` | Search issues |
| `mcp__github__add_issue_comment` | Add comments |
| `mcp__github__list_issues` | List repository issues |
## Workflow
1. **Determine action**: Create, update, or query?
2. **Gather context**: Get repo info, existing labels, milestones if needed
3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md)
4. **Execute**: Call the appropriate MCP tool
5. **Confirm**: Report the issue URL to user
## Creating Issues
### Required Parameters
```
owner: repository owner (org or user)
repo: repository name
title: clear, actionable title
body: structured markdown content
```
### Optional Parameters
```
labels: ["bug", "enhancement", "documentation", ...]
assignees: ["username1", "username2"]
milestone: milestone number (integer)
```
### Title Guidelines
- Start with type prefix when useful: `[Bug]`, `[Feature]`, `[Docs]`
- Be specific and actionable
- Keep under 72 characters
- Examples:
- `[Bug] Login fails with SSO enabled`
- `[Feature] Add dark mode support`
- `Add unit tests for auth module`
### Body Structure
Always use the templates in [references/templates.md](references/templates.md). Choose based on issue type:
| User Request | Template |
|--------------|----------|
| Bug, error, broken, not working | Bug Report |
| Feature, enhancement, add, new | Feature Request |
| Task, chore, refactor, update | Task |
## Updating Issues
Use `mcp__github__update_issue` with:
```
owner, repo, issue_number (required)
title, body, state, labels, assignees, milestone (optional - only changed fields)
```
State values: `open`, `closed`
## Examples
### Example 1: Bug Report
**User**: "Create a bug issue - the login page crashes when using SSO"
**Action**: Call `mcp__github__create_issue` with:
```json
{
"owner": "github",
"repo": "awesome-copilot",
"title": "[Bug] Login page crashes when using SSO",
"body": "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behavior\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behavior\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]\n\n## Additional Context\nReported by user.",
"labels": ["bug"]
}
```
### Example 2: Feature Request
**User**: "Create a feature request for dark mode with high priority"
**Action**: Call `mcp__github__create_issue` with:
```json
{
"owner": "github",
"repo": "awesome-copilot",
"title": "[Feature] Add dark mode support",
"body": "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes\n\n## Alternatives Considered\nNone specified.\n\n## Additional Context\nHigh priority request.",
"labels": ["enhancement", "high-priority"]
}
```
## Common Labels
Use these standard labels when applicable:
| Label | Use For |
|-------|---------|
| `bug` | Something isn't working |
| `enhancement` | New feature or improvement |
| `documentation` | Documentation updates |
| `good first issue` | Good for newcomers |
| `help wanted` | Extra attention needed |
| `question` | Further information requested |
| `wontfix` | Will not be addressed |
| `duplicate` | Already exists |
| `high-priority` | Urgent issues |
## Tips
- Always confirm the repository context before creating issues
- Ask for missing critical information rather than guessing
- Link related issues when known: `Related to #123`
- For updates, fetch current issue first to preserve unchanged fields

90
skills/github-issues/references/templates.md Normal file
View File

@@ -0,0 +1,90 @@
# Issue Templates
Copy and customize these templates for issue bodies.
## Bug Report Template
```markdown
## Description
[Clear description of the bug]
## Steps to Reproduce
1. [First step]
2. [Second step]
3. [And so on...]
## Expected Behavior
[What should happen]
## Actual Behavior
[What actually happens]
## Environment
- Browser: [e.g., Chrome 120]
- OS: [e.g., macOS 14.0]
- Version: [e.g., v1.2.3]
## Screenshots/Logs
[If applicable]
## Additional Context
[Any other relevant information]
```
## Feature Request Template
```markdown
## Summary
[One-line description of the feature]
## Motivation
[Why is this feature needed? What problem does it solve?]
## Proposed Solution
[How should this feature work?]
## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
## Alternatives Considered
[Other approaches considered and why they weren't chosen]
## Additional Context
[Mockups, examples, or related issues]
```
## Task Template
```markdown
## Objective
[What needs to be accomplished]
## Details
[Detailed description of the work]
## Checklist
- [ ] [Subtask 1]
- [ ] [Subtask 2]
- [ ] [Subtask 3]
## Dependencies
[Any blockers or related work]
## Notes
[Additional context or considerations]
```
## Minimal Template
For simple issues:
```markdown
## Description
[What and why]
## Tasks
- [ ] [Task 1]
- [ ] [Task 2]
```

368
skills/web-design-reviewer/SKILL.md Normal file
View File

@@ -0,0 +1,368 @@
---
name: web-design-reviewer
description: 'This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level.'
---
# Web Design Reviewer
This skill enables visual inspection and validation of website design quality, identifying and fixing issues at the source code level.
## Scope of Application
- Static sites (HTML/CSS/JS)
- SPA frameworks such as React / Vue / Angular / Svelte
- Full-stack frameworks such as Next.js / Nuxt / SvelteKit
- CMS platforms such as WordPress / Drupal
- Any other web application
## Prerequisites
### Required
1. **Target website must be running**
- Local development server (e.g., `http://localhost:3000`)
- Staging environment
- Production environment (for read-only reviews)
2. **Browser automation must be available**
- Screenshot capture
- Page navigation
- DOM information retrieval
3. **Access to source code (when making fixes)**
- Project must exist within the workspace
## Workflow Overview
```mermaid
flowchart TD
A[Step 1: Information Gathering] --> B[Step 2: Visual Inspection]
B --> C[Step 3: Issue Fixing]
C --> D[Step 4: Re-verification]
D --> E{Issues Remaining?}
E -->|Yes| B
E -->|No| F[Completion Report]
```
---
## Step 1: Information Gathering Phase
### 1.1 URL Confirmation
If the URL is not provided, ask the user:
> Please provide the URL of the website to review (e.g., `http://localhost:3000`)
### 1.2 Understanding Project Structure
When making fixes, gather the following information:
| Item | Example Question |
|------|------------------|
| Framework | Are you using React / Vue / Next.js, etc.? |
| Styling Method | CSS / SCSS / Tailwind / CSS-in-JS, etc. |
| Source Location | Where are style files and components located? |
| Review Scope | Specific pages only or entire site? |
### 1.3 Automatic Project Detection
Attempt automatic detection from files in the workspace:
```
Detection targets:
├── package.json → Framework and dependencies
├── tsconfig.json → TypeScript usage
├── tailwind.config → Tailwind CSS
├── next.config → Next.js
├── vite.config → Vite
├── nuxt.config → Nuxt
└── src/ or app/ → Source directory
```
### 1.4 Identifying Styling Method
| Method | Detection | Edit Target |
|--------|-----------|-------------|
| Pure CSS | `*.css` files | Global CSS or component CSS |
| SCSS/Sass | `*.scss`, `*.sass` | SCSS files |
| CSS Modules | `*.module.css` | Module CSS files |
| Tailwind CSS | `tailwind.config.*` | className in components |
| styled-components | `styled.` in code | JS/TS files |
| Emotion | `@emotion/` imports | JS/TS files |
| CSS-in-JS (other) | Inline styles | JS/TS files |
---
## Step 2: Visual Inspection Phase
### 2.1 Page Traversal
1. Navigate to the specified URL
2. Capture screenshots
3. Retrieve DOM structure/snapshot (if possible)
4. If additional pages exist, traverse through navigation
### 2.2 Inspection Items
#### Layout Issues
| Issue | Description | Severity |
|-------|-------------|----------|
| Element Overflow | Content overflows from parent element or viewport | High |
| Element Overlap | Unintended overlapping of elements | High |
| Alignment Issues | Grid or flex alignment problems | Medium |
| Inconsistent Spacing | Padding/margin inconsistencies | Medium |
| Text Clipping | Long text not handled properly | Medium |
#### Responsive Issues
| Issue | Description | Severity |
|-------|-------------|----------|
| Non-mobile Friendly | Layout breaks on small screens | High |
| Breakpoint Issues | Unnatural transitions when screen size changes | Medium |
| Touch Targets | Buttons too small on mobile | Medium |
#### Accessibility Issues
| Issue | Description | Severity |
|-------|-------------|----------|
| Insufficient Contrast | Low contrast ratio between text and background | High |
| No Focus State | Cannot determine state during keyboard navigation | High |
| Missing alt Text | No alternative text for images | Medium |
#### Visual Consistency
| Issue | Description | Severity |
|-------|-------------|----------|
| Font Inconsistency | Mixed font families | Medium |
| Color Inconsistency | Non-unified brand colors | Medium |
| Spacing Inconsistency | Non-uniform spacing between similar elements | Low |
### 2.3 Viewport Testing (Responsive)
Test at the following viewports:
| Name | Width | Representative Device |
|------|-------|----------------------|
| Mobile | 375px | iPhone SE/12 mini |
| Tablet | 768px | iPad |
| Desktop | 1280px | Standard PC |
| Wide | 1920px | Large display |
---
## Step 3: Issue Fixing Phase
### 3.1 Issue Prioritization
```mermaid
block-beta
columns 1
block:priority["Priority Matrix"]
P1["P1: Fix Immediately\n(Layout issues affecting functionality)"]
P2["P2: Fix Next\n(Visual issues degrading UX)"]
P3["P3: Fix If Possible\n(Minor visual inconsistencies)"]
end
```
### 3.2 Identifying Source Files
Identify source files from problematic elements:
1. **Selector-based Search**
- Search codebase by class name or ID
- Explore style definitions with `grep_search`
2. **Component-based Search**
- Identify components from element text or structure
- Explore related files with `semantic_search`
3. **File Pattern Filtering**
```
Style files: src/**/*.css, styles/**/*
Components: src/components/**/*
Pages: src/pages/**, app/**
```
### 3.3 Applying Fixes
#### Framework-specific Fix Guidelines
See [references/framework-fixes.md](references/framework-fixes.md) for details.
#### Fix Principles
1. **Minimal Changes**: Only make the minimum changes necessary to resolve the issue
2. **Respect Existing Patterns**: Follow existing code style in the project
3. **Avoid Breaking Changes**: Be careful not to affect other areas
4. **Add Comments**: Add comments to explain the reason for fixes where appropriate
---
## Step 4: Re-verification Phase
### 4.1 Post-fix Confirmation
1. Reload browser (or wait for development server HMR)
2. Capture screenshots of fixed areas
3. Compare before and after
### 4.2 Regression Testing
- Verify that fixes haven't affected other areas
- Confirm responsive display is not broken
### 4.3 Iteration Decision
```mermaid
flowchart TD
A{Issues Remaining?}
A -->|Yes| B[Return to Step 2]
A -->|No| C[Proceed to Completion Report]
```
**Iteration Limit**: If more than 3 fix attempts are needed for a specific issue, consult the user
---
## Output Format
### Review Results Report
```markdown
# Web Design Review Results
## Summary
| Item | Value |
|------|-------|
| Target URL | {URL} |
| Framework | {Detected framework} |
| Styling | {CSS / Tailwind / etc.} |
| Tested Viewports | Desktop, Mobile |
| Issues Detected | {N} |
| Issues Fixed | {M} |
## Detected Issues
### [P1] {Issue Title}
- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description of the issue}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}
- **Screenshot**: Before/After
### [P2] {Issue Title}
...
## Unfixed Issues (if any)
### {Issue Title}
- **Reason**: {Why it was not fixed/could not be fixed}
- **Recommended Action**: {Recommendations for user}
## Recommendations
- {Suggestions for future improvements}
```
---
## Required Capabilities
| Capability | Description | Required |
|------------|-------------|----------|
| Web Page Navigation | Access URLs, page transitions | ✅ |
| Screenshot Capture | Page image capture | ✅ |
| Image Analysis | Visual issue detection | ✅ |
| DOM Retrieval | Page structure retrieval | Recommended |
| File Read/Write | Source code reading and editing | Required for fixes |
| Code Search | Code search within project | Required for fixes |
---
## Reference Implementation
### Implementation with Playwright MCP
[Playwright MCP](https://github.com/microsoft/playwright-mcp) is recommended as the reference implementation for this skill.
| Capability | Playwright MCP Tool | Purpose |
|------------|---------------------|---------|
| Navigation | `browser_navigate` | Access URLs |
| Snapshot | `browser_snapshot` | Retrieve DOM structure |
| Screenshot | `browser_take_screenshot` | Images for visual inspection |
| Click | `browser_click` | Interact with interactive elements |
| Resize | `browser_resize` | Responsive testing |
| Console | `browser_console_messages` | Detect JS errors |
#### Configuration Example (MCP Server)
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--caps=vision"]
}
}
}
```
### Other Compatible Browser Automation Tools
| Tool | Features |
|------|----------|
| Selenium | Broad browser support, multi-language support |
| Puppeteer | Chrome/Chromium focused, Node.js |
| Cypress | Easy integration with E2E testing |
| WebDriver BiDi | Standardized next-generation protocol |
The same workflow can be implemented with these tools. As long as they provide the necessary capabilities (navigation, screenshot, DOM retrieval), the choice of tool is flexible.
---
## Best Practices
### DO (Recommended)
- ✅ Always save screenshots before making fixes
- ✅ Fix one issue at a time and verify each
- ✅ Follow the project's existing code style
- ✅ Confirm with user before major changes
- ✅ Document fix details thoroughly
### DON'T (Not Recommended)
- ❌ Large-scale refactoring without confirmation
- ❌ Ignoring design systems or brand guidelines
- ❌ Fixes that ignore performance
- ❌ Fixing multiple issues at once (difficult to verify)
---
## Troubleshooting
### Problem: Style files not found
1. Check dependencies in `package.json`
2. Consider the possibility of CSS-in-JS
3. Consider CSS generated at build time
4. Ask user about styling method
### Problem: Fixes not reflected
1. Check if development server HMR is working
2. Clear browser cache
3. Rebuild if project requires build
4. Check CSS specificity issues
### Problem: Fixes affecting other areas
1. Rollback changes
2. Use more specific selectors
3. Consider using CSS Modules or scoped styles
4. Consult user to confirm impact scope

475
skills/web-design-reviewer/references/framework-fixes.md Normal file
View File

@@ -0,0 +1,475 @@
# Framework-specific Fix Guide
This document explains specific fix techniques for each framework and styling method.
---
## Pure CSS / SCSS
### Fixing Layout Overflow
```css
/* Before: Overflow occurs */
.container {
width: 100%;
}
/* After: Control overflow */
.container {
width: 100%;
max-width: 100%;
overflow-x: hidden;
}
```
### Text Clipping Prevention
```css
/* Single line truncation */
.text-truncate {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
/* Multi-line truncation */
.text-clamp {
display: -webkit-box;
-webkit-line-clamp: 3;
-webkit-box-orient: vertical;
overflow: hidden;
}
/* Word wrapping */
.text-wrap {
word-wrap: break-word;
overflow-wrap: break-word;
hyphens: auto;
}
```
### Spacing Unification
```css
/* Unify spacing with CSS custom properties */
:root {
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 1.5rem;
--spacing-xl: 2rem;
}
.card {
padding: var(--spacing-md);
margin-bottom: var(--spacing-lg);
}
```
### Improving Contrast
```css
/* Before: Insufficient contrast */
.text {
color: #999999;
background-color: #ffffff;
}
/* After: Meets WCAG AA standards */
.text {
color: #595959; /* Contrast ratio 7:1 */
background-color: #ffffff;
}
```
---
## Tailwind CSS
### Layout Fixes
```jsx
{/* Before: Overflow */}
<div className="w-full">
<img src="..." />
</div>
{/* After: Overflow control */}
<div className="w-full max-w-full overflow-hidden">
<img src="..." className="w-full h-auto object-contain" />
</div>
```
### Text Clipping Prevention
```jsx
{/* Single line truncation */}
<p className="truncate">Long text...</p>
{/* Multi-line truncation */}
<p className="line-clamp-3">Long text...</p>
{/* Allow wrapping */}
<p className="break-words">Long text...</p>
```
### Responsive Support
```jsx
{/* Mobile-first responsive */}
<div className="
flex flex-col gap-4
md:flex-row md:gap-6
lg:gap-8
">
<div className="w-full md:w-1/2 lg:w-1/3">
Content
</div>
</div>
```
### Spacing Unification (Tailwind Config)
```javascript
// tailwind.config.js
module.exports = {
theme: {
extend: {
spacing: {
'18': '4.5rem',
'22': '5.5rem',
},
},
},
}
```
### Accessibility Improvements
```jsx
{/* Add focus state */}
<button className="
bg-blue-500 text-white
hover:bg-blue-600
focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2
">
Button
</button>
{/* Improve contrast */}
<p className="text-gray-700 bg-white"> {/* Changed from text-gray-500 */}
Readable text
</p>
```
---
## React + CSS Modules
### Fixes in Module Scope
```css
/* Component.module.css */
/* Before */
.container {
display: flex;
}
/* After: Add overflow control */
.container {
display: flex;
flex-wrap: wrap;
overflow: hidden;
max-width: 100%;
}
```
### Component-side Fixes
```jsx
// Component.jsx
import styles from './Component.module.css';
// Before
<div className={styles.container}>
// After: Add conditional class
<div className={`${styles.container} ${isOverflow ? styles.overflow : ''}`}>
```
---
## styled-components / Emotion
### Style Fixes
```jsx
// Before
const Container = styled.div`
width: 100%;
`;
// After
const Container = styled.div`
width: 100%;
max-width: 100%;
overflow-x: hidden;
@media (max-width: 768px) {
padding: 1rem;
}
`;
```
### Responsive Support
```jsx
const Card = styled.div`
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 1.5rem;
@media (max-width: 1024px) {
grid-template-columns: repeat(2, 1fr);
}
@media (max-width: 640px) {
grid-template-columns: 1fr;
gap: 1rem;
}
`;
```
### Consistency with Theme
```jsx
// theme.js
export const theme = {
colors: {
primary: '#2563eb',
text: '#1f2937',
textLight: '#4b5563', // Improved contrast
},
spacing: {
sm: '0.5rem',
md: '1rem',
lg: '1.5rem',
},
};
// Usage
const Text = styled.p`
color: ${({ theme }) => theme.colors.text};
margin-bottom: ${({ theme }) => theme.spacing.md};
`;
```
---
## Vue (Scoped Styles)
### Fixing Scoped Styles
```vue
<template>
<div class="container">
<p class="text">Content</p>
</div>
</template>
<style scoped>
/* Applied only to this component */
.container {
max-width: 100%;
overflow: hidden;
}
.text {
/* Fix: Improve contrast */
color: #374151; /* Was: #9ca3af */
}
/* Responsive */
@media (max-width: 768px) {
.container {
padding: 1rem;
}
}
</style>
```
### Deep Selectors (Affecting Child Components)
```vue
<style scoped>
/* Override child component styles (use cautiously) */
:deep(.child-class) {
margin-bottom: 1rem;
}
</style>
```
---
## Next.js / App Router
### Global Style Fixes
```css
/* app/globals.css */
:root {
--foreground: #171717;
--background: #ffffff;
}
/* Prevent layout overflow */
html, body {
max-width: 100vw;
overflow-x: hidden;
}
/* Prevent image overflow */
img {
max-width: 100%;
height: auto;
}
```
### Fixes in Layout Components
```tsx
// app/layout.tsx
export default function RootLayout({ children }) {
return (
<html lang="en">
<body className="min-h-screen flex flex-col">
<header className="sticky top-0 z-50">
{/* Header */}
</header>
<main className="flex-1 container mx-auto px-4 py-8">
{children}
</main>
<footer>
{/* Footer */}
</footer>
</body>
</html>
);
}
```
---
## Common Patterns
### Fixing Flexbox Layout Issues
```css
/* Before: Items overflow */
.flex-container {
display: flex;
gap: 1rem;
}
/* After: Wrap and size control */
.flex-container {
display: flex;
flex-wrap: wrap;
gap: 1rem;
}
.flex-item {
flex: 1 1 300px; /* grow, shrink, basis */
min-width: 0; /* Prevent flexbox overflow issues */
}
```
### Fixing Grid Layout Issues
```css
/* Before: Fixed column count */
.grid-container {
display: grid;
grid-template-columns: repeat(4, 1fr);
}
/* After: Auto-adjust */
.grid-container {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 1.5rem;
}
```
### Organizing z-index
```css
/* Systematize z-index */
:root {
--z-dropdown: 100;
--z-sticky: 200;
--z-modal-backdrop: 300;
--z-modal: 400;
--z-tooltip: 500;
}
.modal {
z-index: var(--z-modal);
}
```
### Adding Focus States
```css
/* Add focus state to all interactive elements */
button:focus-visible,
a:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
outline: 2px solid #2563eb;
outline-offset: 2px;
}
/* Customize focus ring */
.custom-focus:focus-visible {
outline: none;
box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.5);
}
```
---
## Debugging Techniques
### Visualizing Element Boundaries
```css
/* Use only during development */
* {
outline: 1px solid red !important;
}
```
### Detecting Overflow
```javascript
// Run in console to detect overflow elements
document.querySelectorAll('*').forEach(el => {
if (el.scrollWidth > el.clientWidth) {
console.log('Horizontal overflow:', el);
}
if (el.scrollHeight > el.clientHeight) {
console.log('Vertical overflow:', el);
}
});
```
### Checking Contrast Ratio
```javascript
// Use Chrome DevTools Lighthouse or axe DevTools
// Or check at the following site:
// https://webaim.org/resources/contrastchecker/
```

236
skills/web-design-reviewer/references/visual-checklist.md Normal file
View File

@@ -0,0 +1,236 @@
# Visual Inspection Checklist
This document is a comprehensive checklist of items to verify during web design visual inspection.
---
## 1. Layout Verification
### Structural Integrity
- [ ] Header is correctly fixed/positioned at the top of the screen
- [ ] Footer is positioned at the bottom of the screen or end of content
- [ ] Main content area is center-aligned with appropriate width
- [ ] Sidebar (if present) is positioned correctly
- [ ] Navigation is displayed in the intended position
### Overflow
- [ ] Horizontal scrollbar is not unintentionally displayed
- [ ] Content does not overflow from parent elements
- [ ] Images fit within parent containers
- [ ] Tables do not exceed container width
- [ ] Code blocks wrap or scroll appropriately
### Alignment
- [ ] Grid items are evenly distributed
- [ ] Flex item alignment is correct
- [ ] Text alignment (left/center/right) is consistent
- [ ] Icons and text are vertically aligned
- [ ] Form labels and input fields are correctly positioned
---
## 2. Typography Verification
### Readability
- [ ] Body text font size is sufficient (minimum 16px recommended)
- [ ] Line height is appropriate (1.5-1.8 recommended)
- [ ] Characters per line is appropriate (40-80 characters recommended)
- [ ] Spacing between paragraphs is sufficient
- [ ] Heading size hierarchy is clear
### Text Handling
- [ ] Long words wrap appropriately
- [ ] URLs and code are handled properly
- [ ] No text clipping occurs
- [ ] Ellipsis (...) displays correctly
- [ ] Language-specific line breaking rules work correctly
### Fonts
- [ ] Web fonts load correctly
- [ ] Fallback fonts are appropriate
- [ ] Font weights are as intended
- [ ] Special characters and emoji display correctly
---
## 3. Color & Contrast Verification
### Accessibility (WCAG Standards)
- [ ] Body text: Contrast ratio 4.5:1 or higher (AA)
- [ ] Large text (18px+ bold or 24px+): 3:1 or higher
- [ ] Interactive element borders: 3:1 or higher
- [ ] Focus indicators: Sufficient contrast with background
### Color Consistency
- [ ] Brand colors are unified
- [ ] Link colors are consistent
- [ ] Error state red is unified
- [ ] Success state green is unified
- [ ] Hover/active state colors are appropriate
### Color Vision Diversity
- [ ] Information conveyed by shape and text, not just color
- [ ] Charts and diagrams consider color vision diversity
- [ ] Error messages don't rely solely on color
---
## 4. Responsive Verification
### Mobile (~640px)
- [ ] Content fits within screen width
- [ ] Touch targets are 44x44px or larger
- [ ] Text is readable size
- [ ] No horizontal scrolling occurs
- [ ] Navigation is mobile-friendly (hamburger menu, etc.)
- [ ] Form inputs are easy to use
### Tablet (641px~1024px)
- [ ] Layout is optimized for tablet
- [ ] Two-column layouts display appropriately
- [ ] Image sizes are appropriate
- [ ] Sidebar show/hide is appropriate
### Desktop (1025px~)
- [ ] Maximum width is set and doesn't break on extra-large screens
- [ ] Spacing is sufficient
- [ ] Multi-column layouts function correctly
- [ ] Hover states are implemented
### Breakpoint Transitions
- [ ] Layout transitions smoothly when screen size changes
- [ ] Layout doesn't break at intermediate sizes
- [ ] No content disappears or duplicates
---
## 5. Interactive Element Verification
### Buttons
- [ ] Default state is clear
- [ ] Hover state exists (desktop)
- [ ] Focus state is visually clear
- [ ] Active (pressed) state exists
- [ ] Disabled state is distinguishable
- [ ] Loading state (if applicable)
### Links
- [ ] Links are visually identifiable
- [ ] Visited links are distinguishable (if needed)
- [ ] Hover state exists
- [ ] Focus state is clear
### Form Elements
- [ ] Input field boundaries are clear
- [ ] Placeholder text contrast is appropriate
- [ ] Visual feedback on focus
- [ ] Error state display
- [ ] Required field indication
- [ ] Dropdowns function correctly
---
## 6. Images & Media Verification
### Images
- [ ] Images display at appropriate size
- [ ] Aspect ratio is maintained
- [ ] High resolution display support (@2x)
- [ ] Display when image fails to load
- [ ] Lazy loading behavior works
### Video & Embeds
- [ ] Videos fit within containers
- [ ] Aspect ratio is maintained
- [ ] Embedded content is responsive
- [ ] iframes don't overflow
---
## 7. Accessibility Verification
### Keyboard Navigation
- [ ] All interactive elements accessible via Tab key
- [ ] Focus order is logical
- [ ] Focus traps are appropriate (modals, etc.)
- [ ] Skip to content link exists
### Screen Reader Support
- [ ] Images have alt text
- [ ] Forms have labels
- [ ] ARIA labels are appropriately set
- [ ] Heading hierarchy is correct (h1→h2→h3...)
### Motion
- [ ] Animations are not excessive
- [ ] prefers-reduced-motion is supported (if possible)
---
## 8. Performance-related Visual Issues
### Loading
- [ ] Font FOUT/FOIT is minimal
- [ ] No layout shift (CLS) occurs
- [ ] No jumping when images load
- [ ] Skeleton screens are appropriate (if applicable)
### Animation
- [ ] Animations are smooth (60fps)
- [ ] No performance issues when scrolling
- [ ] Transitions are natural
---
## Priority Matrix
| Priority | Category | Examples |
|----------|----------|----------|
| P0 (Critical) | Functionality breaking | Complete element overlap, content disappearance |
| P1 (High) | Serious UX issues | Unreadable text, inoperable buttons |
| P2 (Medium) | Moderate issues | Alignment issues, spacing inconsistencies |
| P3 (Low) | Minor issues | Slight positioning differences, minor color variations |
---
## Verification Tools
### Browser DevTools
- Elements panel: DOM and style inspection
- Lighthouse: Performance and accessibility audits
- Device toolbar: Responsive testing
### Accessibility Tools
- axe DevTools
- WAVE
- Color Contrast Analyzer
### Automation Tools
- Playwright (screenshot comparison)
- Percy / Chromatic (Visual Regression Testing)