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
This commit is contained in:
2026-07-04 11:11:11 +00:00
parent 8463c87dfc
commit 4ea9e21ead
8 changed files with 142 additions and 36 deletions

View File

@@ -33,6 +33,7 @@ bash scripts/new-agent.sh security-reviewer ~
| `SKILL.md` | Skill instructions for agents |
| `scripts/new-agent.sh` | Scaffolds Claude Code and Copilot CLI agent files from templates |
| `references/deployment-modes.md` | Plugin vs project vs user scope: restrictions, scoped identifiers, path conventions |
| `references/scripts.md` | Conventions for new-agent.sh and any future scripts: contract, template variables, file placement, error messages |
| `references/sources.md` | Research provenance — sources that informed this skill |
| `assets/templates/claude-code.md` | Annotated Claude Code agent definition template |
| `assets/templates/copilot.agent.md` | Annotated Copilot CLI agent definition template |

View File

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

View File

@@ -18,7 +18,8 @@ description: FILL IN: Action-first description of what this agent does and when
# Use Agent(type1,type2) to restrict which subagent types this agent can spawn.
# Omit Agent entirely to prevent this agent from spawning subagents.
# Never available to subagents regardless of tools field:
# AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup
# AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers
# Exception: ExitPlanMode IS available when parent session runs in permissionMode: plan
# model: sonnet
# Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID.
@@ -45,6 +46,19 @@ description: FILL IN: Action-first description of what this agent does and when
# background: false
# Optional. Set true to force background execution.
# disallowedTools: mcp__filesystem__write_file
# Optional. Space-separated denylist, applied before the tools allowlist.
# Supports mcp__* glob patterns (e.g. mcp__filesystem__* to block all filesystem tools).
# skills:
# - skill-name
# Optional. Skill names preloaded into this agent's context at startup.
# Different from the source_keys metadata field (which is provenance-only).
# initialPrompt: "Start by reading the README."
# Optional. 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 (not subagent) activation.
# source_keys:
# - slug-name
# Development-only. Add when research sources informed this agent (slugs must match agents/sources.md).

View File

@@ -1,7 +1,12 @@
---
# GitHub Copilot CLI agent definition
# File extension MUST be .agent.md — a plain .md file is not picked up by Copilot.
# 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.
#
# 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.
@@ -22,20 +27,10 @@ description: FILL IN: Action-first description of what this agent does and when
# web — web search and fetch (aliases: WebSearch, WebFetch)
# For MCP tools: "server-name/tool-name" or "server-name/*"
# target: github-copilot
# Optional. Which runtime loads this file.
# vscode — VS Code Copilot only
# github-copilot — Copilot CLI / cloud agents only
# both (default) — loaded by both runtimes
# user-invocable: true
# Optional. Set false to hide from manual invocation (auto-select only).
# disable-model-invocation: false
# Optional. Set true to require explicit user invocation; prevents auto-selection.
# 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

View File

@@ -1,9 +1,17 @@
---
source_keys: []
---
# references/
## deployment-modes.md
Agent scope hierarchy, precedence rules, and per-scope restrictions. Covers: which fields are silently ignored for plugin agents (Claude Code and Copilot CLI), scoped identifiers for plugin subdirectory agents, cache isolation behaviour, and Copilot CLI path conventions. Loaded conditionally from SKILL.md when the destination is a plugin directory.
## scripts.md
Conventions for the `new-agent.sh` scaffold script and any future scripts added to this skill. Covers: what scripts should and should not do, file placement, error handling, template variable conventions, and the no-interactive-prompts rule.
## sources.md
Research provenance record for this skill. Lists the upstream research sources (claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md, the templates, and the deployment-modes reference. Used by `skill-audit` to validate the provenance chain.

View File

@@ -3,6 +3,7 @@ source_keys:
- context7-websites-code-claude
- claude-code-plugins-docs
- claude-code-subagents-docs
- context7-github-en-copilot
- github-custom-agents-configuration
- github-cli-plugin-reference
---

View File

@@ -0,0 +1,42 @@
---
source_keys: []
---
# Scripts Reference
Conventions for `scripts/new-agent.sh` and any future scripts in this skill.
## Contract
All scripts in this skill must follow these rules:
- **No interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via positional arguments, flags, or environment variables.
- **Structured output** — file paths and status messages to stderr; nothing to stdout unless a downstream tool needs to consume it.
- **Idempotent** — "create if not exists" per file. The scaffold script skips any file that already exists; agents may safely re-run it.
- **Meaningful exit codes** — `0` success, `1` invalid arguments or precondition failure. Document in `--help`.
- **Self-contained** — no external package installs at runtime. The script uses only bash builtins and POSIX tools (`sed`, `mkdir`, `cat`).
## Template variables
The scaffold script uses `sed "s/AGENT_NAME/$AGENT_NAME/g"` to substitute the agent name into templates. Template files must use `AGENT_NAME` (all caps, no delimiters) as the substitution token.
Do not add additional substitution tokens unless you update both the template files and the script in the same edit pass.
## File placement
The script creates files at paths determined by scope detection (plugin / project / user). Scope is detected from the presence of `plugin.json` or `.claude-plugin/plugin.json` in the root directory. If scope detection logic changes, update the `new-agent.sh` usage comment and `SKILL.md` Step 1 scope detection table in the same pass.
## Error messages
On failure, state: what went wrong, what was expected, what to try. Example:
```
Error: agent-name must use lowercase letters, numbers, and hyphens only.
No leading, trailing, or consecutive hyphens.
Received: 'My_Agent'
```
Vague errors leave agents unable to self-correct.
## --help output
Keep `--help` concise — it may enter the agent's context window. Include: usage line, argument descriptions with scope detection table, exit codes. Omit prose explanations.

View File

@@ -7,6 +7,9 @@ source_keys:
- github-custom-agents-configuration
- github-cli-plugin-reference
- github-plugins-creating
- github-plugins-finding-installing
- github-plugins-marketplace
- github-sdk-custom-agents
---
# Sources
@@ -16,7 +19,7 @@ source_keys:
- **URL:** context7:/websites/code_claude
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format
- **Contributing files:** SKILL.md, assets/templates/claude-code.md, references/deployment-modes.md
- **Contributing files:** SKILL.md, references/deployment-modes.md
- **Status:** `extracted`
## claude-code-plugins-docs
@@ -32,7 +35,7 @@ source_keys:
- **URL:** https://code.claude.com/docs/en/sub-agents
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations
- **Contributing files:** SKILL.md, assets/templates/claude-code.md, references/deployment-modes.md
- **Contributing files:** SKILL.md, references/deployment-modes.md
- **Status:** `extracted`
## context7-github-en-copilot
@@ -40,7 +43,7 @@ source_keys:
- **URL:** context7:/websites/github_en_copilot
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, and marketplace
- **Contributing files:** SKILL.md, assets/templates/copilot.agent.md, references/deployment-modes.md
- **Contributing files:** SKILL.md, references/deployment-modes.md
- **Status:** `extracted`
## github-custom-agents-configuration
@@ -48,7 +51,7 @@ source_keys:
- **URL:** https://docs.github.com/en/copilot/reference/custom-agents-configuration
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** Reference for cloud and IDE custom agent definition format — frontmatter fields, tool aliases, MCP server config, secrets interpolation, scoping hierarchy
- **Contributing files:** SKILL.md, assets/templates/copilot.agent.md, references/deployment-modes.md
- **Contributing files:** SKILL.md, references/deployment-modes.md
- **Status:** `extracted`
## github-cli-plugin-reference
@@ -56,7 +59,7 @@ source_keys:
- **URL:** https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** Full CLI plugin reference — plugin.json schema, marketplace.json schema, all CLI commands and flags, install specification formats, loading precedence, env vars, LSP config
- **Contributing files:** SKILL.md, scripts/new-agent.sh, references/deployment-modes.md
- **Contributing files:** SKILL.md, references/deployment-modes.md
- **Status:** `extracted`
## github-plugins-creating
@@ -64,5 +67,29 @@ source_keys:
- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** How-to for creating Copilot CLI plugins — plugin structure, agent and skill authoring, hooks format, MCP config, development lifecycle
- **Contributing files:** SKILL.md, assets/templates/copilot.agent.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## github-plugins-finding-installing
- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** User-facing guide to discovering and installing CLI plugins — marketplace browsing commands, install/update/uninstall workflow
- **Contributing files:** (none)
- **Status:** `extracted`
## github-plugins-marketplace
- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** How-to for creating and publishing a plugin marketplace — marketplace.json structure, hosting options, registration commands
- **Contributing files:** (none)
- **Status:** `extracted`
## github-sdk-custom-agents
- **URL:** https://docs.github.com/en/copilot/how-tos/copilot-sdk/features/custom-agents
- **Research doc:** plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md
- **Description:** SDK custom agent API — CustomAgentConfig fields in all five languages, session config, sub-agent lifecycle events, tool scoping, permission handling
- **Contributing files:** (none)
- **Status:** `extracted`