Defame1297
311e7cd22c
Six defects, each one a place where two files that an author reads in the same sitting told them different things — or where the trim dropped a rule and nothing noticed because no gate covers prose. **"Use proactively" contradicted itself across the pair.** All three agent templates said to add it where the runtime should delegate unprompted, while `agent-audit`'s `KyberforgeCopilot.ProactivePhrase` rule grades it a hard FAIL in any `*.agent.md` — which is the Copilot half of every project/user pair *and* the vendor-neutral plugin-scope file, since that compiles to a real Copilot agent downstream. Following the template produced a file the repo's own gate rejects. The phrase is now permitted in exactly one place, the Claude Code `.md`, and `references/contract.md` carries the per-file table plus the consequence authors ask about next: a pair whose CC half has it and whose Copilot half does not is correct, because `agent-audit` checks that both halves describe the same job, not that they match word for word. **The output-schema rule contradicted itself inside one file.** `contract.md` said any content only one branch reaches moves to `references/`, and then offered an "Output format template" body pattern with no qualification. Stated once now, so it is not re-litigated: an output schema stays in the body only when every flow produces it and it is roughly 50 words or less. No third option. **Gotchas tiers disagreed with the script.** `validate.sh` emits the entry count through `suggest()` and exits 0, while `skill-author` and `skill-audit` both called more than five entries a FAIL. Whether a given gotcha earns its place is judgment, so the prose moves to the script's tier rather than the reverse. The paraphrase rule stays a FAIL and is explicitly marked as the auditor's call — no script detects it. **The dispatch exemplar was cited at the wrong number.** `apm-workflow`'s body is 421 words; 554 is its whole-file count. Both `contract.md` and `body-discipline.md` cited 554 while describing a body budget, so an author calibrating against the exemplar overshot by ~30% — the exact whole-file/body-only conflation those two sections exist to warn against, reproduced inside the warning. **"Error handling" came back as a required body element.** It was one of four and is the one that gets dropped, and dropping it is not neutral: an agent handed malformed input with no instruction invents a recovery, and a subagent's invented recovery is invisible to its caller until the output is wrong. Restored in `agent-audit`'s rubric as a SUGGESTION, in `agent-author`'s contract and both scope checklists as a required element, and as an `## Errors` section in all three templates. **`skill-author` Step 4 gains the one check the audit misses.** An empty body reports `PASS SKILL.md body word count 0` — a word gate cannot tell "concise" from "absent". Step 4 now hand-checks for a non-empty section, and its commit verification is conditioned on actually being inside a git worktree, which a skill under `~/.claude/skills/` is not. Also here: absolute repo paths removed from `skill-author`'s SKILL.md and contract.md in favour of naming the skill (`zoom-out`'s description is quoted inline instead of pointed at), the boundary-target universe documented to match the resolver, a two-hops-from-SKILL.md limit on reference chains, and `new-agent.sh`'s next-steps output naming the description budget and the deliberate absence of an agent body gate. Refs: ADR-0020
82 lines
4.3 KiB
Plaintext
82 lines
4.3 KiB
Plaintext
---
|
|
<!-- GitHub Copilot CLI agent definition (CLI format — path: .github/agents/<name>.agent.md)
|
|
File extension MUST be .agent.md — a plain .md file is not picked up by Copilot CLI.
|
|
Fill in all FILL IN: placeholders. Remove or uncomment optional fields as needed.
|
|
Body length limit: 30,000 characters — content beyond this is silently truncated.
|
|
Delete template comments before shipping.
|
|
|
|
NOTE: This template is for the CLI format. The cloud/IDE format (path: .github/copilot/agents/<name>.md,
|
|
extension: .md) supports additional fields: target, user-invocable, disable-model-invocation, mcp-servers.
|
|
Do not add those fields here — they are silently ignored by the CLI runtime. -->
|
|
|
|
name: AGENT_NAME
|
|
<!-- Required. Kebab-case identifier. Home-directory version wins on name collision. -->
|
|
|
|
description: FILL IN: Use when <trigger>. <One capability clause.> Not <thing> -> <name>.
|
|
<!-- Required. Used by the runtime for automatic agent selection, and preloaded into
|
|
every session whether or not this agent is ever used. Three parts, nothing else:
|
|
a trigger clause opening "Use when", at most one capability clause, and a
|
|
boundary clause naming a real sibling skill or agent.
|
|
250 characters is the target, 400 the hard ceiling (ADR-0020).
|
|
Do not open with an action verb ("Reviews...", "Analyzes...") — that rule was deleted.
|
|
Never write "Use proactively" here. It steers the Claude Code runtime and does nothing
|
|
in Copilot, and agent-audit's KyberforgeCopilot.ProactivePhrase grades it a hard FAIL.
|
|
Otherwise keep the wording matched to the Claude Code half of the pair: agent-audit
|
|
checks that both halves describe the same job, not that they are byte-identical, so
|
|
dropping the CC-only phrase here is not a pair-consistency finding.
|
|
Example: "Use when a diff needs checking for injected credentials before it
|
|
merges. Not prose or style linting -> `lint-runner`." -->
|
|
|
|
<!-- tools: ["read", "search", "edit"]
|
|
Optional. Array of tool names. Omit = all available tools. [] = no tools.
|
|
Copilot tool aliases (use these, not Claude Code names):
|
|
execute — run shell commands (aliases: shell, Bash, powershell)
|
|
read — read file contents (aliases: Read, NotebookRead)
|
|
edit — modify files (aliases: Edit, MultiEdit, Write, NotebookEdit)
|
|
search — search files (aliases: Grep, Glob)
|
|
agent — invoke sub-agents (aliases: custom-agent, Task)
|
|
web — web search and fetch (aliases: WebSearch, WebFetch)
|
|
For MCP tools: "server-name/tool-name" or "server-name/*" -->
|
|
|
|
<!-- model: claude-sonnet-4-5
|
|
Optional. Model to run this agent on.
|
|
Cloud/IDE-only fields (target, user-invocable, disable-model-invocation, mcp-servers)
|
|
are not valid in this CLI format — use the .github/copilot/agents/<name>.md path for those. -->
|
|
|
|
<!-- source_keys:
|
|
- slug-name
|
|
Development-only. Add when research sources informed this agent (slugs must match sources.md at the plugin root).
|
|
Omit when no research was used. Not a Copilot runtime field — silently ignored. -->
|
|
|
|
<!-- DO NOT include these Claude Code-only fields:
|
|
maxTurns, isolation, memory, permissionMode, effort, hooks, mcpServers -->
|
|
---
|
|
|
|
FILL IN: System prompt body. Should match the Claude Code version — the agent's task is the same across providers.
|
|
|
|
You are a FILL IN: role description. When invoked, FILL IN: primary action.
|
|
|
|
<!-- Delegate, don't restate. If an installed skill already owns a procedure this agent
|
|
needs, name it ("invoke `git-commits`") instead of transcribing it — a body that
|
|
restates a procedure an invocable skill owns is an agent-audit FAIL. One job per
|
|
agent. Delete this comment before shipping. -->
|
|
|
|
## Inputs
|
|
|
|
FILL IN: What inputs does this agent expect? (files, context, parameters)
|
|
|
|
## Process
|
|
|
|
FILL IN: Steps the agent takes. Be specific about ordering if it matters.
|
|
|
|
## Output
|
|
|
|
FILL IN: What does the agent produce? Format, location, structure.
|
|
|
|
## Errors
|
|
|
|
FILL IN: What does the agent do on malformed, missing or contradictory input?
|
|
State whether it stops and reports, or degrades to a named fallback — and what it
|
|
tells the caller either way. An agent with no error handling invents a recovery,
|
|
and an invented recovery is invisible until the output is wrong.
|