copilot-security-instructions copilot-instructions.md

Copilot authoring guidelines for customization Markdown files

These instructions apply when you create or edit any of the following files:

• agents/*.agent.md
• prompts/*.prompt.md
• instructions/*.instructions.md
• skills/**/SKILL.md

General Markdown rules

• Use ATX headings (#, ##, ###) and keep a clean hierarchy (one # at top).
• Prefer short paragraphs and bullet lists; avoid overly long blocks of text.
• Use fenced code blocks for any code or config. Label the fence language (yaml, bash, json, md, etc.).
• Never place YAML frontmatter anywhere except the very top of the file.
• Always separate YAML frontmatter from body with a blank line after the closing ---.
• Keep instructions unambiguous, testable, and scoped:
  • Use “MUST / SHOULD / MAY” for requirements.
  • Add acceptance criteria when helpful.
• Avoid contradictions across files. If two instruction files could both apply, ensure they agree.

YAML frontmatter conventions

• Use --- on the first line and --- to close the frontmatter block.
• Prefer quoted strings when values contain special characters (:, *, {}, #, @, etc.).
• Use lower-kebab-case for identifiers (e.g., name: markdown-authoring).

Authoring standards per file type

A) Custom agent profiles: agents/*.agent.md

• Frontmatter MUST include:
  • description (required)
  • name (recommended; otherwise filename is used)
• Frontmatter MAY include:
  • tools (list of tool names/aliases)
  • model (IDE-supported)
  • target (vscode or github-copilot), if you want environment-specific availability
• Body MUST:
  • Define the agent’s role, boundaries, and output format expectations.
  • State what the agent should do when missing info (ask concise questions or propose safe defaults).
  • Include formatting rules for produced Markdown (headings, lists, code fences, links).
• Keep the agent prompt focused on a single domain (e.g., “authoring Copilot customization files”).

B) Prompt files: prompts/*.prompt.md