awesome-copilot/CONFIG.md

Configuration File System

The Awesome Copilot repository supports a configuration file system that allows you to easily manage which prompts, instructions, chat modes, and collections are included in your project.

Installation

Via Git Clone (Required)

# Clone the repository
git clone https://github.com/AstroSteveo/awesome-copilot
cd awesome-copilot

# Install dependencies
npm install

# Now you can use the CLI tool
node awesome-copilot.js help

Note: The awesome-copilot package is not yet published to npm, so you must clone the repository to use the CLI tool.

Quick Start

1. Initialize Your Project

Navigate to your project directory where you want to add awesome-copilot customizations, then run:

# Initialize with default configuration
node /path/to/awesome-copilot/awesome-copilot.js init

# Or initialize with a specific name
node /path/to/awesome-copilot/awesome-copilot.js init my-project.config.yml

Tip: You can create an alias or add the awesome-copilot directory to your PATH for easier access:

# Add to your ~/.bashrc or ~/.zshrc
alias awesome-copilot="node /path/to/awesome-copilot/awesome-copilot.js"

This creates:

• Configuration file (awesome-copilot.config.yml)
• .github/ directory structure
• VS Code settings pointing to .github/ directories
• No changes to .gitignore (files in .github/ are typically tracked)

2. Enable Desired Items

You can enable items either by editing the YAML file directly or by using the CLI helpers that toggle entries for you.

Option A: Edit the configuration file manually

Set items to true in the configuration file to include them:

version: "1.0"
project:
  name: "My Project"
  description: "A project using awesome-copilot customizations"
  output_directory: ".github"
  # Recommended default is .github; explicit output_directory will be respected
prompts:
  create-readme: true
  editorconfig: true
  generate-tests: false
instructions:
  typescript-best-practices: true
  testing-standards: true
  react: false
chatmodes:
  architect: true
  dba: false
  specification: true
collections:
  frontend-web-dev: true
  csharp-dotnet-development: false

Option B: Manage items from the CLI (recommended for quick toggles)

# Inspect what is enabled in the default configuration file
node /path/to/awesome-copilot/awesome-copilot.js list instructions

# Enable a single prompt
node /path/to/awesome-copilot/awesome-copilot.js toggle prompts create-readme on

# Disable everything in a section
node /path/to/awesome-copilot/awesome-copilot.js toggle instructions all off

# Work with a named configuration file
node /path/to/awesome-copilot/awesome-copilot.js list prompts --config team.config.yml

The CLI prints the number of enabled items and estimates the combined size of their instructions/prompts so you can avoid exceeding Copilot Agent's context window. If the total size approaches a risky threshold, you'll see a warning.

3. Apply Configuration

# Apply default configuration file
node /path/to/awesome-copilot/awesome-copilot.js apply

# Or apply specific configuration file  
node /path/to/awesome-copilot/awesome-copilot.js apply my-project.config.yml

This will copy the enabled files to your project's .github directory (or the directory specified in the config).

Configuration File Format

Top-level Structure

version: "1.0"                    # Required: Config format version
project:                          # Optional: Project metadata
  name: "My Project"              # Project name
  description: "Project desc"     # Project description  
  output_directory: ".github"     # Where to copy files (default: .github)
prompts: {}                       # Enable/disable prompts
instructions: {}                  # Enable/disable instructions
chatmodes: {}                     # Enable/disable chat modes
collections: {}                   # Enable/disable collections

Individual Items

Set any item to true to include it, false to exclude it:

prompts:
  create-readme: true             # Include this prompt
  generate-tests: false           # Exclude this prompt

Collections

Collections are special - when you enable a collection, it automatically includes all items in that collection:

collections:
  frontend-web-dev: true          # Includes all prompts, instructions, and chat modes in this collection

Output Structure

When you apply a configuration, files are organized as follows:

.github/
├── prompts/
│   └── *.prompt.md             # Prompts for /awesome-copilot commands
├── chatmodes/
│   └── *.chatmode.md           # Chat modes for VS Code
└── instructions/
    └── *.instructions.md       # Instructions that auto-apply to coding

VS Code automatically detects these files through the generated .vscode/settings.json configuration.

NPM Scripts

If you've cloned the repository locally, you can also use npm scripts:

# Initialize configuration
npm run config:init

# Apply configuration
npm run config:apply

# Access CLI help
npm run config help

VS Code Integration

The node awesome-copilot.js init command automatically configures VS Code to detect your customizations:

• Creates .vscode/settings.json with proper file locations
• Points to .github/ directories instead of framework directories
• Maintains separation between your project and the awesome-copilot framework

No manual VS Code configuration needed!

GitHub Copilot Repository Instructions

Awesome Copilot can generate a .github/copilot-instructions.md file that provides repository-level instructions to GitHub Copilot. This feature supports GitHub's native repository instructions capability, which automatically applies instructions to all Copilot interactions within your repository.

Generating Repository Instructions

# Generate basic repository instructions file
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions

# Generate with full instruction content included
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions --consolidated

# Custom output location
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions --output=.copilot/instructions.md

# Generate without header
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions --no-header

Template Options

• repository (default): Lists enabled instructions with references to individual files
• consolidated: Includes full content from all enabled instruction files
• basic: Simple list without detailed formatting

Benefits of Repository Instructions

• Automatic Application: Instructions apply to all team members without manual configuration
• Version Control: Instructions are tracked with your code and evolve with your project
• IDE Agnostic: Works across VS Code, Visual Studio, GitHub Copilot CLI, and web interfaces
• Consistency: Ensures all team members get the same Copilot behavior
• No Setup Required: New team members automatically get proper instructions

Integration with Configuration

The repository instructions are generated based on your enabled instructions in the configuration file:

instructions:
  csharp: true       # Included in repository instructions
  python: true       # Included in repository instructions
  java: false        # Excluded from repository instructions
  
collections:
  testing-automation: true  # All instructions in this collection included

Workflow Integration

Repository instructions work seamlessly with the existing workflow:

1. Configure: Enable instructions in your config file
2. Apply: Run awesome-copilot apply to copy files to your project
3. Generate: Run generate-repo-instructions to create the repository instructions file
4. Commit: Add the generated file to version control
5. Collaborate: Team members automatically get consistent Copilot behavior

Examples

Frontend React Project

version: "1.0"
project:
  name: "React Frontend"
  output_directory: ".github"
collections:
  frontend-web-dev: true
prompts:
  create-readme: true
  editorconfig: true
chatmodes:
  specification: true

Backend .NET Project

version: "1.0"
project:
  name: ".NET API"
  output_directory: ".github"
collections:
  csharp-dotnet-development: true
instructions:
  testing-standards: true
prompts:
  create-specification: true

Full Stack Project

version: "1.0"
project:
  name: "Full Stack App"
  output_directory: ".github"
collections:
  frontend-web-dev: true
  csharp-dotnet-development: true
  database-data-management: true
chatmodes:
  architect: true
  specification: true

Migration from Manual Approach

If you were previously copying files manually or using an older version:

1. Remove manually copied files from your .github directory
2. Clone awesome-copilot repository: git clone https://github.com/AstroSteveo/awesome-copilot
3. Run node /path/to/awesome-copilot/awesome-copilot.js init to create a clean setup
4. Edit the config to enable the same items you were using manually
5. Run node /path/to/awesome-copilot/awesome-copilot.js apply to get a clean, managed setup

The approach uses the standard .github/ directory for Copilot customizations. If you previously used .awesome-copilot/, set project.output_directory: ".awesome-copilot" to keep that structure.

Benefits

• Centralized Management: One file controls all your Copilot customizations
• VS Code Integration: Automatic configuration, no manual setup required
• Clear Separation: Framework files separated from your project files
• Version Control Friendly: Config file tracks what's enabled, generated files are ignored
• Easy Updates: Re-run apply command after awesome-copilot updates
• Collection Support: Enable entire curated sets with one setting
• Minimal Footprint: Only enabled files are copied to your project