Files

Defame1297 ede3f06689 fix(kyberforge): restore the authoring rules the ADR-0020 trim dropped

Diffing each retrofitted SKILL.md against its replacement references/ files found
rules that existed on main and now existed nowhere — relocated in intent, deleted in
fact. A trim that loses a rule is not progressive disclosure, it is data loss with a
smaller word count.

Three had no survivor. The least-privilege guidance for `tools` kept its mechanics
and lost the "restrict to what the agent needs" half, so the remaining text read as
encouragement to omit the field. The improve flow lost its regression check, so
nothing compared the closing audit against the pre-edit state and a PASS quietly
becoming a SUGGESTION went unnoticed — restored on both halves of the author pair,
since agent-author had dropped its equivalent too. And agent bodies lost "would the
agent get this wrong without it?", which mattered more than it looks: ADR-0020
deliberately sets no body word gate for agents, three of the four already sit
between 933 and 1,199 words, and the delegation check only fires on procedure a
skill already owns. That heuristic was the only brake left.

Two more were reachable only from the wrong scope. agent-author tells the reader to
load only the file for the resolved scope, but the mcp__ glob syntax for
disallowedTools and the five tools no subagent ever receives had both landed in
project-user-scope.md. disallowedTools is the ONLY permitted fence at plugin/APM
scope, so the scope that needs the syntax most could not reach it, and a plugin-scope
run could write a body telling the agent to ask the user a question.

Two documents were actively wrong rather than merely thin. agent-audit told auditors
that validate.sh resolves boundary targets for skills only; it runs at both scopes,
so the auditor was hand-resolving what the script had already decided and could
contradict it. And skill-audit routed to its script-troubleshooting reference
whenever validate.sh "fails" — but it exits 1 on ordinary content FAILs, the normal
outcome for the whole #99 population, so 1,302 words loaded on nearly every audit.
A context-budget regression inside the skill that enforces the context budget.

Finally, two illustrations taught the shape the gate ERRORs on, unfenced, while an
adjacent rubric called it a hard ERROR.

LESSONS.md records the reference-chain depth rule flipping from "one level deep" to
"two hops, never three". ADR-0020 is silent on it and the reversal rode entirely on
the diff; the looser rule is what mandatory dispatch requires.

Refs: #99
ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi

2026-08-16 19:49:38 +00:00

5.5 KiB

Raw Blame History

source_keys

claude-code-subagents-docs

context7-github-en-copilot

github-custom-agents-configuration

github-cli-plugin-reference

Project and user scope — the Claude Code / Copilot pair

Two files per agent, written in one pass and kept in step: a Claude Code .md and a Copilot CLI .agent.md. The system prompt body is the same in both — the agent's task does not change with the provider. The frontmatter is not.

Scope	Claude Code	Copilot CLI
Project	`.claude/agents/<name>.md`	`.github/agents/<name>.agent.md`
User	`~/.claude/agents/<name>.md`	`~/.copilot/agents/<name>.agent.md`

Claude Code file

name — lowercase letters and hyphens only, unique within the scope. Claude Code discards a duplicate silently.

description — write it against references/contract.md. It is the primary signal for autonomous delegation.

tools — an allowlist. Write it, and restrict it to the tools the agent actually needs; omitting it inherits every tool from the parent, which is the right value only when the agent genuinely needs all of them. Least privilege is the default, not the exception. Use Agent(type1,type2) to restrict which subagent types this agent may spawn, and omit Agent entirely to stop it spawning any. Five tools reach no subagent whatever this field says — AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup and WaitForMcpServers — so listing one buys nothing. The single exception is ExitPlanMode, available when the parent session runs permissionMode: plan.

disallowedTools — a denylist, applied before tools and taking precedence over it. Supports mcp__<server>, mcp__<server>__* and mcp__* globs. Both a YAML list and a delimited string are accepted; this repo writes the comma-separated string form (disallowedTools: Edit, Write, NotebookEdit) — match it.

model — set it when the agent needs a different capability tier (haiku for fast lookups, opus for deep reasoning). Resolution order is CLAUDE_CODE_SUBAGENT_MODEL → the per-invocation parameter → this field → the main session model, so the frontmatter value is a low-priority default rather than a guarantee.

Optional fields worth considering, none of which exist at plugin/APM scope:

maxTurns — cap agentic turns on a bounded task, to stop a runaway
effort — low for a single lookup, high or above for multi-file analysis; omit to inherit
memory — user, project or local; only when cross-session state is genuinely needed
isolation: worktree — only when the agent modifies files and needs an isolated copy
skills — skill names preloaded at agent startup; unrelated to the source_keys metadata field
color — the UI tile colour (red, blue, green, yellow, purple, orange, pink, cyan)
background — true forces background execution
initialPrompt — auto-submitted as the first turn when the agent activates as the main session thread; set it only for a main-thread agent, never for a subagent

hooks, mcpServers and permissionMode are honoured at these two scopes and nowhere else — a plugin agent carrying them is ignored silently.

A subdirectory under agents/ does not affect the agent's name at these scopes; it does at plugin scope, which is one reason references/deployment-modes.md recommends keeping agents flat.

Copilot file

Two Copilot formats exist, with different paths and different field sets. Pick one:

CLI format — what the scaffold writes.

Path: .github/agents/<name>.agent.md (project) or ~/.copilot/agents/<name>.agent.md (user)
The .agent.md extension is mandatory: Copilot CLI does not pick up a plain .md file in agents/, and fails silently rather than reporting it
Fields: name (required, must equal the filename stem), description (required), tools (optional)
tools uses Copilot aliases, not Claude tool names: execute (shell), read, edit, search, agent, web; MCP tools as server-name/tool-name or server-name/*

Cloud/IDE format — for Copilot Chat in VS Code or on GitHub.com.

Path: .github/copilot/agents/<name>.md — a plain .md, in a different directory
Adds target (vscode, github-copilot, or omit for both), user-invocable, disable-model-invocation and mcp-servers (processed by the cloud runtime, ignored in VS Code). These four are inert in the CLI format — do not write them there
This is the only format that can express the invocation axis in frontmatter; see the Invocation axis section of references/contract.md

Both formats truncate a body past 30,000 characters silently.

Copilot has no permissionMode, maxTurns, isolation, memory, effort, hooks or mcpServers. Never let those cross over from the Claude Code file.

Before invoking `agent-audit`

Both files:

name present and kebab-case; description written to references/contract.md
System prompt body present, non-empty and equivalent across the pair
Body covers all four required elements: inputs expected, process steps, output format, error handling — what the agent does on malformed, missing or contradictory input
No FILL IN: placeholder and no  template comment left

Copilot file only:

Extension is .agent.md (CLI format), and name matches the filename stem
No Claude Code-only field present
Body under 30,000 characters

Then return to the flow reference you came from.

5.5 KiB Raw Blame History

Project and user scope — the Claude Code / Copilot pair

Claude Code file

Copilot file

Before invoking agent-audit

5.5 KiB

Raw Blame History

Before invoking `agent-audit`