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.