# 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.