docs: document proposed custom-agent effort frontmatter (Option A)

[romanstetsenko]

Summary

Documents the proposed custom-agent �ffort frontmatter field for #2904 Option A (dedicated �ffort field, parallel to model).

Adds a "Custom Agents" reference section to README.md covering:

• Existing frontmatter fields (
  ame, description, model)
• The new proposed �ffort field with values low / medium (default) / high / xhigh
• Precedence: agent �ffort overrides global �ffortLevel config and the --effort / --reasoning-effort CLI flag for that agent; falls back to session-level effort when unset
• Clamping behavior for models that do not support a given level (consistent with --effort today)

Important scope note (please read)

github/copilot-cli is an install/distribution + issue-tracking repository only — it contains install.sh, README.md, changelog.md, and issue-triage workflows, but no CLI source (confirmed: 16 tracked files, languages = Shell only). The actual YAML-frontmatter parser and the CustomAgentConfig type live in the private binary / copilot-sdk (sibling request copilot-sdk#1131).

Therefore this PR cannot include the runtime implementation or tests in this repo — they are out of scope here. This PR establishes the documented contract so the SDK loader, the docs site, and user-authored .agent.md files stay aligned on field name, values, and precedence. The �ffort field is clearly marked as Preview / proposed in the README so readers know runtime support is pending.

Type of change

• Documentation
• Install script
• Other (please describe):

Checklist

• Change is scoped to README.md
• Markdown renders correctly (tables, code fences, blockquote)
• Runtime implementation (tracked separately in copilot-sdk#1131)
• Tests / validation of the parser (not possible in this repo)

Related

• Issue: Custom Agent YAML Frontmatter Should Support Reasoning Effort #2904
• SDK-side type: copilot-sdk#1131

Closes #2904

[romanstetsenko]

Closing draft: removing per request. No runtime implementation possible in this install-only repo.