GitHub Copilot (github/awesome-copilot)

GitHub Copilot

https://github.com/github/awesome-copilot
Admin
Enhance your GitHub Copilot experience with community-contributed instructions, prompts, and...

Tokens:1,228,950
Snippets:11,126
Trust Score:8.2
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Awesome GitHub Copilot Customizations

This project provides a curated collection of customizations for GitHub Copilot, including prompts, instructions, chat modes, and collections. It serves as a community-driven repository that enhances the GitHub Copilot experience across different programming languages, frameworks, and development scenarios. The repository includes Node.js scripts for validating, generating documentation, and creating new collection manifests from YAML files.

The core functionality revolves around organizing developer resources into four categories: reusable prompts for specific tasks, coding instructions that apply to file patterns, specialized AI chat modes for different roles, and collections that bundle related items. The project includes automated tooling for parsing YAML collection manifests, extracting metadata from markdown files, generating installation badges, and producing comprehensive README documentation for each category.

## APIs and Key Functions

### YAML Collection Parser

Parses collection YAML files and extracts structured data including metadata, items, and display settings.

```javascript
const { parseCollectionYaml } = require('./yaml-parser');

// Parse a collection manifest file
const collection = parseCollectionYaml('./collections/python-mcp-development.collection.yml');

console.log(collection);
// Output:
// {
//   id: 'python-mcp-development',
//   name: 'Python MCP Server Development',
//   description: 'Complete toolkit for building Model Context Protocol servers...',
//   tags: ['python', 'mcp', 'model-context-protocol', 'fastmcp', 'server-development'],
//   items: [
//     { path: 'instructions/python-mcp-server.instructions.md', kind: 'instruction' },
//     { path: 'prompts/python-mcp-server-generator.prompt.md', kind: 'prompt' },
//     { path: 'chatmodes/python-mcp-expert.chatmode.md', kind: 'chat-mode', usage: '...' }
//   ],
//   display: { ordering: 'manual', show_badge: true }
// }
```

### Collection Validation

Validates collection manifests against schema requirements including ID format, item paths, and field constraints.

```javascript
const { exec } = require('child_process');

// Run validation on all collection files
exec('node validate-collections.js', (error, stdout, stderr) => {
  console.log(stdout);
  // Output:
  // Validating 25 collection files...
  //
  // Validating python-mcp-development.collection.yml...
  // ✅ python-mcp-development.collection.yml is valid
  //
  // Validating typescript-mcp-development.collection.yml...
  // ✅ typescript-mcp-development.collection.yml is valid
  //
  // ✅ All 25 collections are valid
  // 🎉 Collection validation passed

  if (error) {
    console.error(`Validation failed: ${error.message}`);
    process.exit(1);
  }
});
```

### Collection Creation Tool

Interactive command-line tool for creating new collection manifests with proper structure and validation.

```bash
# Create a new collection interactively
node create-collection.js

# Output:
# 🎯 Collection Creator
# This tool will help you create a new collection manifest.
#
# Collection ID (lowercase, hyphens only): web-security
# Collection name (default: Web Security): Web Security Best Practices
# Description (default: A collection...): Security guidelines for web applications
# Tags (comma-separated, or press Enter for defaults): security, web, best-practices
# ✅ Created collection template: /path/to/collections/web-security.collection.yml

# Create with command-line arguments
node create-collection.js --id=web-security --tags="security,web,best-practices"
```

### Metadata Extraction from Markdown

Extracts titles and descriptions from markdown frontmatter and content for documentation generation.

```javascript
const fs = require('fs');
const path = require('path');

// Read the update-readme.js to access extractTitle and extractDescription
// These functions parse markdown files and extract metadata

function extractTitle(filePath) {
  const content = fs.readFileSync(filePath, 'utf8');
  const lines = content.split('\n');

  // Extract from frontmatter
  let inFrontmatter = false;
  for (const line of lines) {
    if (line.trim() === '---') {
      inFrontmatter = !inFrontmatter;
      continue;
    }
    if (inFrontmatter && line.includes('title:')) {
      return line.substring(line.indexOf('title:') + 6).trim().replace(/^['"]|['"]$/g, '');
    }
  }

  // Fallback to first heading
  for (const line of lines) {
    if (line.startsWith('# ')) {
      return line.substring(2).trim();
    }
  }

  return path.basename(filePath, path.extname(filePath));
}

// Example usage
const title = extractTitle('./prompts/create-readme.prompt.md');
console.log(title); // Output: "Create README"
```

### README Documentation Generator

Generates comprehensive README files for each category with installation badges and metadata tables.

```bash
# Generate all README files
node update-readme.js

# Output:
# Generating category README files...
# Found 89 instruction files
# Found 127 prompt files
# Found 23 chat mode files
# Found 25 collection files
# README.instructions.md updated successfully!
# README.prompts.md updated successfully!
# README.chatmodes.md updated successfully!
# README.collections.md updated successfully!
# Generating individual collection README files...
# python-mcp-development.md updated successfully!
# typescript-mcp-development.md created successfully!
```

### Installation Badge Generator

Creates VS Code and VS Code Insiders installation badges with encoded URLs.

```javascript
// From update-readme.js
const repoBaseUrl = 'https://raw.githubusercontent.com/github/awesome-copilot/main';

function makeBadges(link, type) {
  const akaUrls = {
    instructions: 'https://aka.ms/awesome-copilot/install/instructions',
    prompt: 'https://aka.ms/awesome-copilot/install/prompt',
    mode: 'https://aka.ms/awesome-copilot/install/chatmode'
  };

  const aka = akaUrls[type];
  const vscodeUrl = `${aka}?url=${encodeURIComponent(
    `vscode:chat-${type}/install?url=${repoBaseUrl}/${link}`
  )}`;
  const insidersUrl = `${aka}?url=${encodeURIComponent(
    `vscode-insiders:chat-${type}/install?url=${repoBaseUrl}/${link}`
  )}`;

  return `[![Install in VS Code](badge.svg)](${vscodeUrl})<br />` +
         `[![Install in VS Code Insiders](badge.svg)](${insidersUrl})`;
}

// Generate badges for a prompt
const badges = makeBadges('prompts/create-readme.prompt.md', 'prompt');
console.log(badges);
// Output: Installation badge markdown with encoded URLs
```

### Collection Manifest Schema Validation

Validates individual collection fields including IDs, names, tags, items, and display settings.

```javascript
// Validation functions from validate-collections.js

function validateCollectionId(id) {
  if (!id || typeof id !== 'string') return 'ID is required and must be a string';
  if (!/^[a-z0-9-]+$/.test(id)) return 'ID must contain only lowercase letters, numbers, and hyphens';
  if (id.length < 1 || id.length > 50) return 'ID must be between 1 and 50 characters';
  return null;
}

function validateCollectionItems(items) {
  if (!items || !Array.isArray(items)) return 'Items is required and must be an array';
  if (items.length < 1) return 'At least one item is required';
  if (items.length > 50) return 'Maximum 50 items allowed';

  for (let i = 0; i < items.length; i++) {
    const item = items[i];
    if (!item.path) return `Item ${i + 1} must have a path`;
    if (!['prompt', 'instruction', 'chat-mode'].includes(item.kind)) {
      return `Item ${i + 1} kind must be one of: prompt, instruction, chat-mode`;
    }
  }
  return null;
}

// Example validation
const errors = [];
const idError = validateCollectionId('Python-MCP'); // Invalid: uppercase
if (idError) errors.push(idError);
console.log(errors); // Output: ['ID must contain only lowercase letters, numbers, and hyphens']
```

### Safe File Operation Wrapper

Error handling wrapper for file operations that provides graceful fallbacks.

```javascript
const { safeFileOperation } = require('./yaml-parser');
const fs = require('fs');

// Safely read a file with fallback
const content = safeFileOperation(
  () => fs.readFileSync('./collections/example.yml', 'utf8'),
  './collections/example.yml',
  'default content' // fallback value
);

console.log(content);
// Output: File contents if successful, 'default content' if error occurs
// Errors are logged to console but don't throw
```

### Collection README Generation

Generates individual README files for each collection with item tables and usage information.

```javascript
// From update-readme.js - generateCollectionReadme function

function generateCollectionReadme(collection, collectionId) {
  const name = collection.name || collectionId;
  const description = collection.description || 'No description provided.';
  const tags = collection.tags ? collection.tags.join(', ') : 'None';

  let content = `# ${name}\n\n${description}\n\n`;
  if (collection.tags && collection.tags.length > 0) {
    content += `**Tags:** ${tags}\n\n`;
  }

  content += `## Items in this Collection\n\n`;
  content += `| Title | Type | Description |\n| ----- | ---- | ----------- |\n`;

  // Sort items if ordering is 'alpha'
  const items = [...collection.items];
  if (collection.display?.ordering === 'alpha') {
    items.sort((a, b) => extractTitle(a.path).localeCompare(extractTitle(b.path)));
  }

  for (const item of items) {
    const title = extractTitle(item.path);
    const description = extractDescription(item.path) || 'No description';
    const typeDisplay = item.kind === 'chat-mode' ? 'Chat Mode' :
                        item.kind === 'instruction' ? 'Instruction' : 'Prompt';
    content += `| [${title}](../${item.path}) | ${typeDisplay} | ${description} |\n`;
  }

  return content;
}

// Example: Generate README for a collection
const collection = parseCollectionYaml('./collections/python-mcp-development.collection.yml');
const readme = generateCollectionReadme(collection, 'python-mcp-development');
fs.writeFileSync('./collections/python-mcp-development.md', readme);
```

## Summary and Use Cases

This project serves as a comprehensive toolkit for enhancing GitHub Copilot with community-contributed customizations. Primary use cases include discovering and installing specialized prompts for common development tasks, applying project-wide coding standards through instructions, activating AI personas with chat modes for specific roles, and adopting complete workflows through curated collections. Developers can use the MCP server integration to search and install customizations directly from their editor, or manually browse the generated README files to find relevant resources.

The integration patterns focus on automation and validation workflows. Contributors can use the collection creation tool to generate properly formatted manifests, run validation scripts in CI/CD pipelines to ensure quality, and trigger README generation to automatically update documentation. The YAML parser handles multi-line descriptions and complex collection structures, while the badge generator creates installation links that deep-link into VS Code and VS Code Insiders. The modular design allows each component to function independently while supporting the overall ecosystem of GitHub Copilot customizations.