bw-copilot-resources/docs/authoring.md

Authoring Guide

Choose The Right Primitive

• Use a skill for reusable multi-step workflows, especially if the workflow should work in Copilot CLI as well as VS Code.
• Use a prompt for a lightweight VS Code slash command.
• Use an instruction file for conventions or rules that should influence model behavior.
• Use an agent for a reusable persona with tool restrictions or handoffs.
• Use a hook only when the behavior must be deterministic and enforced in code.

Keep Shared Resources Cheap

• Reuse an existing shared resource before creating a new one.
• Choose the cheapest sufficient primitive for the job instead of defaulting to a long prompt.
• Keep frontmatter, descriptions, and embedded examples concise.
• Prefer targeted inputs such as a file, symbol, or command over broad repo scans.
• State the default output budget when the resource is meant to stay brief.
• Say when the resource should not be used so it does not become a generic, expensive fallback.

Supported Creation Paths

Repo-first

Open this repository in VS Code and create the resource directly in the matching folder.

Local-first

Create the resource from a normal VS Code workspace or user-profile flow, then publish it into this repository with install/publish.sh or install/publish.ps1.

Rule Of Record

If a resource is meant to be shared, the version in this repository is the only version that counts.