awesome-copilot/.github/copilot-instructions.md

.github/copilot-instructions.md — repo-specific guidance for AI agents

Purpose: give an AI coding agent the minimal, high-value facts to be immediately productive in this repository.

Key locations (what to read first)

• README.md — project overview and MCP server notes (README is generated by update-readme.js).
• prompts/, instructions/, chatmodes/, collections/ — primary content types and their file patterns.
• update-readme.js — script that builds README tables and badges; it shows how titles/descriptions are extracted from frontmatter or headings.
• validate-collections.js and yaml-parser.js — collection manifest rules and validation logic (see file-kind checks, ID/tag constraints, and item path checks).

Big picture

• This repo is a curated library of Copilot artifacts: prompts (.prompt.md), instructions (.instructions.md), and chat modes (.chatmode.md). Collections (.collection.yml) reference those files and are validated by validate-collections.js.
• README content is regenerated from source files by running node update-readme.js (or npm run build), which expects predictable frontmatter and filename patterns.

Developer workflows (explicit commands)

• Generate README: npm run build (runs node update-readme.js).
• Validate collections: node validate-collections.js (script exits non‑zero on failure).
• Contributor tasks: all-contributors commands are available (npm run contributors:generate, etc.).
• VS Code tasks are present for generate-readme, validate-collections, and create-collection (see workspace tasks in the README).

Project-specific conventions (discoverable and enforced)

• File extensions map to kinds: prompts → .prompt.md; instructions → .instructions.md; chat modes → .chatmode.md. validate-collections.js enforces this.
• Collection items[].kind must be one of prompt, instruction, chat-mode and the path must point to an existing file with the correct extension.
• Collection IDs and tags: lowercase, hyphen-separated; length and character checks are enforced in validate-collections.js.
• Frontmatter usage: update-readme.js prefers frontmatter title and description. If missing, it falls back to the first # heading or a formatted filename.
• Description handling: single-line description: or multi-line description: | blocks are supported by update-readme.js.

Patterns & examples (copyable references)

• Title extraction: update-readme.js looks for title: in frontmatter, then # heading after frontmatter, then falls back to filename formatting.
• Description extraction: accepts single-line description: '...' (single quotes supported) or multiline description: | and two-space indented lines.
• Collection validation: validate-collections.js checks structure (id/name/description/tags/items/display), enforces MAX_COLLECTION_ITEMS, and verifies that each items[].path exists.

Actionable checklist for AI agents (use before committing)

• New .prompt.md, .instructions.md, or .chatmode.md include frontmatter with title and description (use single quotes for description when needed).
• Filenames are lower-case, words separated by hyphens, and extensions match their kind.
• If you want the artifact listed in README tables, either include frontmatter title/description or ensure a top-level # heading is present.
• If adding a collection .collection.yml: set valid id, name, description, tags, and items matching the validator rules. Run node validate-collections.js locally.
• Run npm run build locally to regenerate the README and confirm the new entries appear as expected.

Notes and cautions

• Avoid changing update-readme.js behavior unless necessary; many repo tools and badge URLs (aka.ms mapping) depend on its link-generation logic.
• validate-collections.js is the authoritative enforcement for collection manifests. Fix validation errors rather than bypassing them.

If you want examples added to this file (sample frontmatter templates, CI snippet to run these checks, or a helper script to lint frontmatter), tell me which example and I'll add it. The following instructions are only to be applied when performing a code review.

README updates

• The new file should be added to the README.md.

Prompt file guide

Only apply to files that end in .prompt.md

• The prompt has markdown front matter.
• The prompt has a mode field specified of either agent or ask.
• The prompt has a description field.
• The description field is not empty.
• The description field value is wrapped in single quotes.
• The file name is lower case, with words separated by hyphens.
• Encourage the use of tools, but it's not required.
• Strongly encourage the use of model to specify the model that the prompt is optimised for.

Instruction file guide

Only apply to files that end in .instructions.md

• The instruction has markdown front matter.
• The instruction has a description field.
• The description field is not empty.
• The description field value is wrapped in single quotes.
• The file name is lower case, with words separated by hyphens.
• The instruction has an applyTo field that specifies the file or files to which the instructions apply. If they wish to specify multiple file paths they should formated like '**.js, **.ts'.

Chat Mode file guide

Only apply to files that end in .chatmode.md

• The chat mode has markdown front matter.
• The chat mode has a description field.
• The description field is not empty.
• The description field value is wrapped in single quotes.
• The file name is lower case, with words separated by hyphens.
• Encourage the use of tools, but it's not required.
• Strongly encourage the use of model to specify the model that the chat mode is optimised for.