fix(kyberforge): apply audit findings to agent-author skill

- Fix Copilot format conflation: split CLI vs cloud/IDE in Step 3,
  clean copilot template to CLI-only fields, add body length limit (30k)
- Add missing CC fields to Step 2: disallowedTools, skills, color,
  initialPrompt, background
- Fix Gotchas: add WaitForMcpServers to unavailable tools list,
  add ExitPlanMode plan-mode carve-out
- Make 'Use proactively' conditional (was unconditional directive)
- Clarify audit invocation to 'Invoke kyberforge:agent-audit skill directly'
- Add 'Would the agent get this wrong?' heuristic to Improve Step 4
- Add agent-audit co-install prerequisite check
- Add pre-audit manual checklist to validate/close step
- Add references/scripts.md for new-agent.sh conventions
- Fix sources.md: remove template/script files from Contributing files
  (templates can't carry YAML provenance without leaking into user files),
  add 3 missing research slugs with (none) contributing files
- Add context7-github-en-copilot to deployment-modes.md source_keys
- Update README.md and references/README.md with new scripts.md entry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9

plugins/kyberforge/skills/agent-author/SKILL.md

@@ -28,7 +28,7 @@ metadata:
 
 - If the agent lives inside a plugin (its path contains a `plugin.json`), bump the plugin version after every change — in both `plugin.json` and `.claude-plugin/plugin.json` in the same edit pass. Convention: new agent → minor bump; improvement or fix → patch bump. Plugin consumers compare this version to detect updates; skipping it makes the change invisible.
 - Plugin agents silently ignore `hooks`, `mcpServers`, and `permissionMode` — these fields have no effect and produce no warning. They only work in `.claude/agents/` or `~/.claude/agents/`.
-- `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, and `ScheduleWakeup` are never available to any subagent regardless of the `tools` field.
+- `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup`, and `WaitForMcpServers` are never available to any subagent regardless of the `tools` field. Exception: `ExitPlanMode` is available when the parent session runs in `permissionMode: plan`.
 - Duplicate `name` values in the same scope: Claude Code silently discards one without warning. Always verify uniqueness before shipping.
 - Plugin agents in subdirectories get scoped identifiers (`plugin:folder:name`). Keep agents flat in `agents/` to avoid this.
 - Copilot CLI agent files **must** use the `.agent.md` extension. A plain `.md` file is not picked up by Copilot.
@@ -59,6 +59,8 @@ Before touching the filesystem, confirm you have:
 
 If any are missing, stop and ask before proceeding.
 
+Verify `kyberforge:agent-audit` is available — it ships with the kyberforge plugin and is co-installed with this skill. If unavailable, stop and tell the user to install the kyberforge plugin before continuing.
+
 ### Step 1 — Scaffold
 
 Run the scaffold script with the agent name and root directory:
@@ -89,7 +91,7 @@ Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder.
 
 **`description`** — the most important field for autonomous delegation:
 - Start with an action verb: "Reviews...", "Analyzes...", "Generates..."
-- Include "Use proactively" to trigger automatic invocation without explicit user direction
+- If this agent should trigger without explicit user direction, include "Use proactively" in the description
 - Specific about the triggering condition and expertise domain
 - Under 300 characters preferred
 
@@ -101,6 +103,11 @@ Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder.
 - `effort`: set to `low` for single-lookup tasks, `high` or above for deep reasoning or multi-file analysis — overrides session effort level; 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
+- `disallowedTools`: space-separated denylist applied before `tools`; supports `mcp__*` glob patterns (e.g. `disallowedTools: mcp__filesystem__*`)
+- `skills`: list of skill names preloaded at agent startup — different from the `source_keys` metadata field
+- `color`: UI color for the agent tile (`red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`)
+- `initialPrompt`: auto-submitted as the first turn when this agent activates as the main session thread; only set when this agent is intended for main-thread activation
+- `background`: set `true` to force background execution
 
 **`source_keys`** — top-level list of research source slugs that informed this agent. Add only when research sources were used (i.e. entries with `` `extracted` `` status are in context from a prior `/research` session). Each slug must match an H2 heading in `agents/sources.md`. Omit entirely when no research was used.
 
@@ -114,17 +121,23 @@ source_keys:
 - Cover: inputs expected, process steps, output format, error handling
 - One job per agent
 
-### Step 3 — Fill in the Copilot CLI agent file (`<name>.agent.md`)
+### Step 3 — Fill in the Copilot agent file
 
-Open the scaffolded Copilot file. Replace every `FILL IN:` placeholder.
+There are **two distinct Copilot agent formats** with different paths and field sets. Choose one based on the deployment target:
 
-**Field differences from Claude Code:**
+**CLI format** (default — what the scaffold creates):
+- Path: `.github/agents/<name>.agent.md` (project) or `<plugin>/agents/<name>.agent.md` (plugin)
+- Extension: **must be `.agent.md`**
+- Supported fields: `name` (required), `description` (required), `tools` (optional)
 - `tools` uses Copilot aliases: `execute` (shell), `read`, `edit`, `search`, `agent`, `web`
-- `target`: `vscode`, `github-copilot`, or omit for both (default: both)
-- `user-invocable`: set `false` to hide from manual invocation (auto-select only)
-- `disable-model-invocation`: set `true` to require explicit user invocation
+- Body length limit: **30,000 characters** — content beyond this is silently truncated
 
-**Do not include Claude Code-only fields**: `maxTurns`, `isolation`, `memory`, `permissionMode`, `effort`, `hooks`, `mcpServers`.
+**Cloud/IDE format** (use when targeting Copilot Chat in VS Code or GitHub.com):
+- Path: `.github/copilot/agents/<name>.md` (note: plain `.md`, different directory)
+- Additional fields available: `target` (`vscode`, `github-copilot`, or omit for both), `user-invocable` (set `false` to hide from manual invocation), `disable-model-invocation` (set `true` to require explicit user invocation), `mcp-servers` (MCP server config — processed by cloud runtime, ignored in VS Code)
+- Body length limit: **30,000 characters** — silently truncated
+
+**Do not include Claude Code-only fields in either format**: `maxTurns`, `isolation`, `memory`, `permissionMode`, `effort`, `hooks`, `mcpServers`.
 
 **`source_keys`** — add the same top-level list as the CC file when research sources were used. Omit when no research was used.
 
@@ -157,21 +170,26 @@ If no research sources are in context, delete `agents/sources.md`.
 
 ### Step 5 — Validate and close
 
+Run this checklist before invoking the audit:
+
 **Claude Code file (`<name>.md`):**
 - [ ] `name` field present, kebab-case, unique in scope
-- [ ] `description` field present, action-first
-- [ ] If plugin scope: no `hooks`, `mcpServers`, or `permissionMode` (silently ignored at plugin scope — move agent to `.claude/agents/` to use them)
+- [ ] `description` field present and action-first
+- [ ] If plugin scope: no `hooks`, `mcpServers`, or `permissionMode` (silently ignored at plugin scope)
 - [ ] System prompt body present and non-empty
+- [ ] No `FILL IN:` placeholders remain
 
-**Copilot file (`<name>.agent.md`):**
+**Copilot CLI file (`<name>.agent.md`):**
 - [ ] File extension is `.agent.md` (not `.md`)
+- [ ] `name` field matches the filename stem (e.g. `name: my-agent` in `my-agent.agent.md`)
 - [ ] `description` field present
 - [ ] No Claude Code-only fields (`maxTurns`, `isolation`, `memory`, `permissionMode`, `effort`)
 - [ ] System prompt body present and non-empty
+- [ ] Body does not exceed 30,000 characters
 
 If the destination is inside a plugin directory, apply a **minor bump** to the `version` field in both `plugin.json` and `.claude-plugin/plugin.json` at the plugin root in the same edit pass (e.g. `1.0.4` → `1.1.0`).
 
-Run `/agent-audit` on the created files to confirm the pair is valid before closing.
+Invoke the `kyberforge:agent-audit` skill directly on the created files to confirm the pair is valid before closing.
 
 ## Improving an existing agent
 
@@ -202,7 +220,7 @@ Before editing, state which root causes were identified, what evidence supports
 
 ### Step 4 — Apply changes
 
-Edit any file the signals point to. Generalize the fix — find the underlying gap, not the specific example that failed. For Copilot files, verify no Claude Code-only fields are introduced.
+Edit any file the signals point to. Generalize the fix — find the underlying gap, not the specific example that failed. For every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused definition consistently outperforms an exhaustive one. For Copilot files, verify no Claude Code-only fields are introduced.
 
 ### Step 5 — Validate and close
 
@@ -210,4 +228,4 @@ Re-run the validation checklist from the create flow's Step 5 on any edited file
 
 If the agent lives inside a plugin directory, apply a **patch bump** to the `version` field in both `plugin.json` and `.claude-plugin/plugin.json` at the plugin root in the same edit pass (e.g. `1.0.4` → `1.0.5`).
 
-Run `/agent-audit` on the edited files to confirm no regressions before closing.
+Invoke the `kyberforge:agent-audit` skill directly on the edited files to confirm no regressions before closing.