github-copilot-starter

$2a

Use this structure:

# {Project Name} — Copilot Instructions

## Project Overview

Brief description of what this project does and its primary purpose.

## Tech Stack

List the primary language, frameworks, and key dependencies.

## Conventions

- Naming: describe naming conventions for files, functions, variables

- Structure: describe how the codebase is organized

- Error handling: describe the project's approach to errors and exceptions

## Workflow

- Describe PR conventions, branch naming, and commit style

- Reference specific instruction files for detailed standards:

  - Language guidelines: `.github/instructions/{language}.instructions.md`

  - Testing: `.github/instructions/testing.instructions.md`

  - Security: `.github/instructions/security.instructions.md`

  - Documentation: `.github/instructions/documentation.instructions.md`

  - Performance: `.github/instructions/performance.instructions.md`

  - Code review: `.github/instructions/code-review.instructions.md`

2. .github/instructions/ Directory

Create specific instruction files:

• {primaryLanguage}.instructions.md - Language-specific guidelines

• testing.instructions.md - Testing standards and practices

• documentation.instructions.md - Documentation requirements

• security.instructions.md - Security best practices

• performance.instructions.md - Performance optimization guidelines

• code-review.instructions.md - Code review standards and GitHub review guidelines

3. .github/skills/ Directory

Create reusable skills as self-contained folders:

• setup-component/SKILL.md - Component/module creation

• write-tests/SKILL.md - Test generation

• code-review/SKILL.md - Code review assistance

• refactor-code/SKILL.md - Code refactoring

• generate-docs/SKILL.md - Documentation generation

• debug-issue/SKILL.md - Debugging assistance

4. .github/agents/ Directory

Always create these 4 agents:

• software-engineer.agent.md

• architect.agent.md

• reviewer.agent.md

• debugger.agent.md

For each, fetch the most specific match from awesome-copilot agents. If none exists, use the generic template.

Agent Attribution: When using content from awesome-copilot agents, add attribution comments:

<!-- Based on/Inspired by: https://github.com/github/awesome-copilot/blob/main/agents/[filename].agent.md -->

5. .github/workflows/ Directory (only if user uses GitHub Actions)

Skip this section entirely if the user answered "no" to GitHub Actions.

Create Coding Agent workflow file:

• copilot-setup-steps.yml - GitHub Actions workflow for Coding Agent environment setup

CRITICAL: The workflow MUST follow this exact structure:

• Job name MUST be copilot-setup-steps

• Include proper triggers (workflow_dispatch, push, pull_request on the workflow file)

• Set appropriate permissions (minimum required)

• Customize steps based on the technology stack provided

Content Guidelines

For each file, follow these principles:

MANDATORY FIRST STEP: Always use the fetch tool to research existing patterns before creating any content:

• Fetch specific instruction from awesome-copilot docs: https://github.com/github/awesome-copilot/blob/main/docs/README.instructions.md

• Fetch specific agents from awesome-copilot docs: https://github.com/github/awesome-copilot/blob/main/docs/README.agents.md

• Fetch specific skills from awesome-copilot docs: https://github.com/github/awesome-copilot/blob/main/docs/README.skills.md

• Check for existing patterns that match the technology stack

Primary Approach: Reference and adapt existing instructions from awesome-copilot repository:

• Use existing content when available - don't reinvent the wheel

• Adapt proven patterns to the specific project context

• Combine multiple examples if the stack requires it

• ALWAYS add attribution comments when using awesome-copilot content

Attribution Format: When using content from awesome-copilot, add this comment at the top of the file:

<!-- Based on/Inspired by: https://github.com/github/awesome-copilot/blob/main/instructions/[filename].instructions.md -->

Examples:

<!-- Based on: https://github.com/github/awesome-copilot/blob/main/instructions/react.instructions.md -->

---

applyTo: "**/*.jsx,**/*.tsx"

description: "React development best practices"

---

# React Development Guidelines

...

<!-- Inspired by: https://github.com/github/awesome-copilot/blob/main/instructions/java.instructions.md -->

<!-- and: https://github.com/github/awesome-copilot/blob/main/instructions/spring-boot.instructions.md -->

---

applyTo: "**/*.java"

description: "Java Spring Boot development standards"

---

# Java Spring Boot Guidelines

...

Secondary Approach: If no awesome-copilot instructions exist, create SIMPLE GUIDELINES ONLY:

• High-level principles and best practices (2-3 sentences each)

• Architectural patterns (mention patterns, not implementation)

• Code style preferences (naming conventions, structure preferences)

• Testing strategy (approach, not test code)

• Documentation standards (format, requirements)

STRICTLY AVOID in .instructions.md files:

• ❌ Writing actual code examples or snippets

• ❌ Detailed implementation steps

• ❌ Test cases or specific test code

• ❌ Boilerplate or template code

• ❌ Function signatures or class definitions

• ❌ Import statements or dependency lists

CORRECT .instructions.md content:

• ✅ "Use descriptive variable names and follow camelCase"

• ✅ "Prefer composition over inheritance"

• ✅ "Write unit tests for all public methods"

• ✅ "Use TypeScript strict mode for better type safety"

• ✅ "Follow the repository's established error handling patterns"

Research Strategy with fetch tool:

• Check awesome-copilot first - Always start here for ALL file types

• Look for exact tech stack matches (e.g., React, Node.js, Spring Boot)

• Look for general matches (e.g., frontend agents, testing skills, review workflows)

• Check the docs and relevant directories directly for related files

• Prefer repo-native examples over inventing new formats

• Only create custom content if nothing relevant exists

Fetch these awesome-copilot directories:

• Instructions: https://github.com/github/awesome-copilot/tree/main/instructions

• Agents: https://github.com/github/awesome-copilot/tree/main/agents

• Skills: https://github.com/github/awesome-copilot/tree/main/skills

Awesome-Copilot Areas to Check:

• Frontend Web Development: React, Angular, Vue, TypeScript, CSS frameworks

• C# .NET Development: Testing, documentation, and best practices

• Java Development: Spring Boot, Quarkus, testing, documentation

• Database Development: PostgreSQL, SQL Server, and general database best practices

• Azure Development: Infrastructure as Code, serverless functions

• Security & Performance: Security frameworks, accessibility, performance optimization

File Structure Standards

Ensure all files follow these conventions:

project-root/

├── .github/

│   ├── copilot-instructions.md

│   ├── instructions/

│   │   ├── [language].instructions.md

│   │   ├── testing.instructions.md

│   │   ├── documentation.instructions.md

│   │   ├── security.instructions.md

│   │   ├── performance.instructions.md

│   │   └── code-review.instructions.md

│   ├── skills/

│   │   ├── setup-component/

│   │   │   └── SKILL.md

│   │   ├── write-tests/

│   │   │   └── SKILL.md

│   │   ├── code-review/

│   │   │   └── SKILL.md

│   │   ├── refactor-code/

│   │   │   └── SKILL.md

│   │   ├── generate-docs/

│   │   │   └── SKILL.md

│   │   └── debug-issue/

│   │       └── SKILL.md

│   ├── agents/

│   │   ├── software-engineer.agent.md

│   │   ├── architect.agent.md

│   │   ├── reviewer.agent.md

│   │   └── debugger.agent.md

│   └── workflows/                        # only if GitHub Actions is used

│       └── copilot-setup-steps.yml

YAML Frontmatter Template

Use this structure for all files:

Instructions (.instructions.md):

---

applyTo: "**/*.{lang-ext}"

description: "Development standards for {Language}"

---

# {Language} coding standards

Apply the repository-wide guidance from `../copilot-instructions.md` to all code.

## General Guidelines

- Follow the project's established conventions and patterns

- Prefer clear, readable code over clever abstractions

- Use the language's idiomatic style and recommended practices

- Keep modules focused and appropriately sized

<!-- Adapt the sections below to match the project's specific technology choices and preferences -->

Skills (SKILL.md):

---

name: {skill-name}

description: {Brief description of what this skill does}

---

# {Skill Name}

{One sentence describing what this skill does. Always follow the repository's established patterns.}

Ask for {required inputs} if not provided.

## Requirements

- Use the existing design system and repository conventions

- Follow the project's established patterns and style

- Adapt to the specific technology choices of this stack

- Reuse existing validation and documentation patterns

Agents (.agent.md):

---

description: Generate an implementation plan for new features or refactoring existing code.

tools: ['codebase', 'web/fetch', 'findTestFiles', 'githubRepo', 'search', 'usages']

model: Claude Sonnet 4

---

# Planning mode instructions

You are in planning mode. Your task is to generate an implementation plan for a new feature or for refactoring existing code.

Don't make any code edits, just generate a plan.

The plan consists of a Markdown document that describes the implementation plan, including the following sections:

* Overview: A brief description of the feature or refactoring task.

* Requirements: A list of requirements for the feature or refactoring task.

* Implementation Steps: A detailed list of steps to implement the feature or refactoring task.

* Testing: A list of tests that need to be implemented to verify the feature or refactoring task.

Execution Steps

• Gather project information - Ask the user for technology stack, project type, and development style if not provided

• Research awesome-copilot patterns:

• Use the fetch tool to explore awesome-copilot directories

• Check instructions: https://github.com/github/awesome-copilot/tree/main/instructions

• Check agents: https://github.com/github/awesome-copilot/tree/main/agents (especially for matching expert agents)

• Check skills: https://github.com/github/awesome-copilot/tree/main/skills

• Document all sources for attribution comments

• Create the directory structure

• Generate main copilot-instructions.md with project-wide standards

• Create language-specific instruction files using awesome-copilot references with attribution

• Generate reusable skills tailored to project needs

• Set up specialized agents, fetching from awesome-copilot where applicable (especially for expert engineer agents matching the tech stack)

• Create the GitHub Actions workflow for Coding Agent (copilot-setup-steps.yml) — skip if user does not use GitHub Actions

• Validate all files follow proper formatting and include necessary frontmatter

Post-Setup Instructions

After creating all files, provide the user with:

• VS Code setup instructions - How to enable and configure the files

• Usage examples - How to use each skill and agent

• Customization tips - How to modify files for their specific needs

• Testing recommendations - How to verify the setup works correctly

Quality Checklist

Before completing, verify:

• All authored Copilot markdown files have proper YAML frontmatter where required

• Language-specific best practices are included

• Files reference each other appropriately using Markdown links

• Skills and agents include relevant descriptions; include MCP/tool-related metadata only when the target Copilot environment actually supports or requires it

• Instructions are comprehensive but not overwhelming

• Security and performance considerations are addressed

• Testing guidelines are included

• Documentation standards are clear

• Code review standards are defined

Workflow Template Structure (only if GitHub Actions is used)

The copilot-setup-steps.yml workflow MUST follow this exact format and KEEP IT SIMPLE:

name: "Copilot Setup Steps"

on:

  workflow_dispatch:

  push:

    paths:

      - .github/workflows/copilot-setup-steps.yml

  pull_request:

    paths:

      - .github/workflows/copilot-setup-steps.yml

jobs:

  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.

  copilot-setup-steps:

    runs-on: ubuntu-latest

    permissions:

      contents: read

    steps:

      - name: Checkout code

        uses: actions/checkout@v5

      # Add ONLY basic technology-specific setup steps here

KEEP WORKFLOWS SIMPLE - Only include essential steps:

Node.js/JavaScript:

- name: Set up Node.js

  uses: actions/setup-node@v4

  with:

    node-version: "20"

    cache: "npm"

- name: Install dependencies

  run: npm ci

- name: Run linter

  run: npm run lint

- name: Run tests

  run: npm test

Python:

- name: Set up Python

  uses: actions/setup-python@v4

  with:

    python-version: "3.11"

- name: Install dependencies

  run: pip install -r requirements.txt

- name: Run linter

  run: flake8 .

- name: Run tests

  run: pytest

Java:

- name: Set up JDK

  uses: actions/setup-java@v4

  with:

    java-version: "17"

    distribution: "temurin"

- name: Build with Maven

  run: mvn compile

- name: Run tests

  run: mvn test

AVOID in workflows:

• ❌ Complex configuration setups

• ❌ Multiple environment configurations

• ❌ Advanced tooling setup

• ❌ Custom scripts or complex logic

• ❌ Multiple package managers

• ❌ Database setup or external services

INCLUDE only:

• ✅ Language/runtime setup

• ✅ Basic dependency installation

• ✅ Simple linting (if standard)

• ✅ Basic test running

• ✅ Standard build commands