fix(kyberforge): address agent-audit audit findings in validate-provenance.sh

## Why

Two issues were found in `validate-provenance.sh` by `/skill-audit`:

1. `find_plugin_root` only walked up looking for bare `plugin.json`, missing
   the `.claude-plugin/plugin.json` layout used by kyberforge plugins — matching
   the logic already present in `validate.sh`.

2. Check numbers in `--help` and inline comments had a gap (0,1,2,4,5,6) from
   a previously removed check, making the numbering confusing to readers.

## Implementation Notes

Check numbers renumbered sequentially 0–5 in both the `--help` output block
and the inline `# --- Check N:` comments. The `find_plugin_root` condition now
mirrors the `detect_scope` function in `validate.sh`.

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

plugins/kyberforge/.claude-plugin/plugin.json

@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.1.2"
+  "version": "1.1.3"
 }

plugins/kyberforge/plugin.json

@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.2"
+  "version": "1.1.3"
 }

plugins/kyberforge/skills/agent-audit/README.md

@@ -20,6 +20,7 @@ Pass the path to either agent file as the argument.
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
 | `references/README.md` | Directory documentation for references/ |
+| `references/description-quality.md` | Qualitative guide for borderline description findings |
 | `references/field-inventory.md` | Authoritative list of valid CC and Copilot agent fields |
 | `references/sources.md` | Research provenance for skill content |
 | `scripts/README.md` | Directory documentation for scripts/ |

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

@@ -4,11 +4,12 @@ description: >
   Use when the user wants to review an agent definition they wrote, says "audit this
   agent", "check if my agent follows best practices", "review my agent file", or wants
   to know if an agent pair is ready to ship — even if they don't use the word "audit".
-  Audits a Claude Code .md and Copilot .agent.md agent file pair — structural
-  validation via validate.sh plus qualitative checks on description and system prompt.
-  Produces a compact findings report (findings only, no PASS noise) with Why and Fix
-  per finding, in the same format as skill-audit. Do not use to fix agent files — use
-  /agent-author instead. Do not use to audit SKILL.md files — use /skill-audit instead.
+  Audits a Claude Code .md and Copilot .agent.md agent file pair across five dimensions:
+  structural validation, provider safety, description quality, body quality, and pair
+  consistency — plus provenance chain validation. Produces a compact findings report
+  (findings only, no PASS noise) with Why and Fix per finding. Do not use to fix agent
+  files — use /agent-author instead. Do not use to audit SKILL.md files — use
+  /skill-audit instead.
 allowed-tools: Bash Read
 metadata:
   category: factory
@@ -22,8 +23,8 @@ metadata:
 
 ## Gotchas
 
-- The unit of authoring is always a pair (CC `.md` + Copilot `.agent.md`). A missing counterpart is always a FAIL, not a warning.
-- Plugin scope is detected by the presence of `plugin.json` in the directory tree — not by the file path pattern. Walk up, don't guess.
+- The unit of authoring in this project is always a pair (CC `.md` + Copilot `.agent.md`). A missing counterpart is a FAIL under the kyberforge project convention — neither the CC nor the Copilot platform itself requires a counterpart file. Label such findings as project convention violations, not platform spec failures.
+- Plugin scope is detected by the presence of `plugin.json` or `.claude-plugin/plugin.json` in the directory tree — not by the file path pattern. Walk up both paths at each level, don't guess.
 - `references/field-inventory.md` must exist for `validate.sh` to run. The script exits with an error if it is missing.
 - Do not output findings while auditing — gather internally, surface in Step 3 report.
 
@@ -34,11 +35,11 @@ bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
 ```
 
-The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file or plugin-silently-ignored fields in a CC file → `### Provider safety`.
+The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`.
 
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `agents/sources.md`. It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
-If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually: required fields present (`name`, `description`, non-empty body), `name` is kebab-case, `name` matches filename stem, no `FILL IN:` placeholders, no CC-only fields in Copilot file.
+If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually: required fields present (`name`, `description`, non-empty body), `name` is kebab-case, Copilot CLI `.agent.md` `name` must match filename stem (CC files are exempt — the CC platform does not require name to match filename), no `FILL IN:` placeholders, no CC-only fields in Copilot file, no Copilot-only fields in CC file (read `references/field-inventory.md` for the authoritative field lists).
 
 ## Step 2 — Qualitative checks
 
@@ -49,13 +50,15 @@ Read both agent files. Work through each dimension internally. Collect findings
 - Specificity: is the trigger condition stated precisely? — SUGGESTION if vague
 - `Use proactively` in a Copilot description: CC-specific phrasing, has no effect in Copilot — SUGGESTION to remove
 
+If a description finding is borderline, read `references/description-quality.md`.
+
 **Body:**
 - Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent
 - One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded
 
 **Pair consistency (cross-file):**
-- `name` field matches between CC and Copilot files — FAIL if mismatch
-- Both system prompt bodies non-empty — FAIL if either is empty
+- Both files exist — FAIL if counterpart is missing (kyberforge project convention; not a platform requirement from either CC or Copilot — label as such)
+- The following checks are covered automatically by `validate.sh`; apply them manually only when the script cannot run: both system prompt bodies non-empty — FAIL if either is empty
 
 ## Step 3 — Report
 
@@ -81,8 +84,11 @@ Close with:
 ## Result
 
 PASS
+PASS · P info
 PASS (N suggestions)
+PASS (N suggestions) · P info
 FAIL (N fails · M suggestions)
+FAIL (N fails · M suggestions) · P info
 Run /agent-author to address findings.
 ```
 

plugins/kyberforge/skills/agent-audit/references/README.md

@@ -1,3 +1,7 @@
+---
+source_keys: []
+---
+
 # references/
 
 Additional documentation agents load on demand.
@@ -6,5 +10,6 @@ Additional documentation agents load on demand.
 
 | File | Purpose |
 |------|---------|
+| `description-quality.md` | Qualitative guide for borderline description findings — action-verb rules, specificity criteria, proactive-use caveat, length limits. |
 | `field-inventory.md` | Canonical list of valid CC and Copilot agent definition fields. Load when the script needs authoritative field lists for structural validation. |
 | `sources.md` | Research provenance records for skill content. Load only when tracing the origin of a specific rule or field constraint. |

plugins/kyberforge/skills/agent-audit/references/description-quality.md

@@ -0,0 +1,49 @@
+---
+source_keys:
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+  - claude-code-subagents-docs
+  - context7-github-en-copilot
+  - github-custom-agents-configuration
+---
+
+# Agent Description Quality Reference
+
+Load this file when a description finding is borderline and you need to make a precise call.
+
+## Action-verb opening
+
+The description must open with an imperative or present-tense verb that describes what the agent does ("Reviews...", "Audits...", "Generates...", "Analyzes..."). Avoid:
+- Noun phrases: "An agent that..." — no verb
+- "This agent..." or "Use this when..." — passive framing
+- "Helps with..." — too vague to be a clear verb
+
+**Borderline call:** "Validates and reviews..." is acceptable — two verbs is fine if both are specific. "Assists in reviewing..." is not — "assists" is vague filler.
+
+## Specificity of trigger condition
+
+The description must state what specifically triggers the agent. Generic phrasing fails:
+- Too vague: "when the user needs help with agents"
+- Acceptable: "when the user says 'audit this agent', 'check if my agent follows best practices', or wants to know if an agent pair is ready to ship"
+
+Include indirect triggers: "even if they don't use the word 'audit'" or "even if the user doesn't phrase it as a review request". If the agent should activate on a recognisable user goal (not just literal keyword matches), name that goal.
+
+**Borderline call:** If the description covers direct triggers but omits common indirect phrasings that a user would plausibly use, mark as SUGGESTION (not FAIL) — the agent still activates, just less reliably.
+
+## `Use proactively`
+
+For CC files: including "Use proactively" signals the CC runtime to offer the agent unprompted when conditions are met. This is CC-specific — use it when the agent should activate without an explicit user request.
+
+For Copilot files: this phrase has no effect. Use `user-invocable: false` / `disable-model-invocation: true` for equivalent Copilot behavior. Flag `Use proactively` in a Copilot description as a SUGGESTION (not FAIL) — it causes no harm, just has no effect.
+
+## Length and hard limits
+
+- CC agent descriptions: no documented character limit, but keep under 500 characters to avoid truncation in UI contexts.
+- Copilot agent descriptions: no separate documented limit, but the overall 30,000-character body limit applies to the full file.
+- Skill descriptions (SKILL.md): hard 1024-character limit enforced by the platform.
+
+## Do not use when
+
+Include a "Do not use when..." clause only if a near-miss agent or skill exists that could steal activations. Omitting it is not a finding. Including it is correct when there is a real confusion risk (e.g., `/agent-audit` vs `/skill-audit`).
+
+**Borderline call:** If the "Do not use when" clause is present but the exclusion described is already obvious from context, mark as SUGGESTION to tighten or remove — not FAIL.

plugins/kyberforge/skills/agent-audit/references/field-inventory.md

@@ -22,3 +22,7 @@ hooks mcpServers permissionMode
 ## copilot-fields
 
 name description tools target model disable-model-invocation user-invocable mcp-servers metadata
+
+## copilot-only-fields
+
+target disable-model-invocation user-invocable mcp-servers metadata

plugins/kyberforge/skills/agent-audit/references/sources.md

@@ -14,7 +14,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, references/field-inventory.md
+- **Contributing files:** SKILL.md, references/field-inventory.md, references/description-quality.md
 - **Status:** `extracted`
 
 ## claude-code-plugins-docs
@@ -22,7 +22,7 @@ source_keys:
 - **URL:** https://code.claude.com/docs/en/plugins
 - **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
 - **Description:** Official Claude Code plugin authoring guide — plugin structure, manifest fields, loading methods, skill namespacing, agent activation, marketplace submission
-- **Contributing files:** SKILL.md, references/field-inventory.md
+- **Contributing files:** SKILL.md, references/field-inventory.md, references/description-quality.md
 - **Status:** `extracted`
 
 ## claude-code-subagents-docs
@@ -30,7 +30,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, references/field-inventory.md
+- **Contributing files:** SKILL.md, references/field-inventory.md, references/description-quality.md
 - **Status:** `extracted`
 
 ## context7-github-en-copilot
@@ -38,7 +38,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, references/field-inventory.md
+- **Contributing files:** SKILL.md, references/field-inventory.md, references/description-quality.md
 - **Status:** `extracted`
 
 ## github-custom-agents-configuration
@@ -46,7 +46,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, references/field-inventory.md
+- **Contributing files:** SKILL.md, references/field-inventory.md, references/description-quality.md
 - **Status:** `extracted`
 
 ## github-cli-plugin-reference

plugins/kyberforge/skills/agent-audit/scripts/validate-provenance.sh

@@ -19,9 +19,9 @@ Checks performed:
   0  source_keys present in agent pair but agents/sources.md absent
   1  FILL IN: placeholders in agents/sources.md
   2  source_keys in agent files → slug exists in agents/sources.md
-  4  Contributing files listed in agents/sources.md exist on disk (plugin-root relative)
-  5  Contributing files back-reference the parent slug in their source_keys
-  6  Research doc field present and not placeholder
+  3  Contributing files listed in agents/sources.md exist on disk (plugin-root relative)
+  4  Contributing files back-reference the parent slug in their source_keys
+  5  Research doc field present and not placeholder
 EOF
 }
 
@@ -61,7 +61,7 @@ else:
 def find_plugin_root(start_dir):
     current = os.path.abspath(start_dir)
     while True:
-        if os.path.isfile(os.path.join(current, 'plugin.json')):
+        if (os.path.isfile(os.path.join(current, 'plugin.json')) or os.path.isfile(os.path.join(current, '.claude-plugin', 'plugin.json'))):
             return current
         parent = os.path.dirname(current)
         if parent == current:
@@ -225,9 +225,9 @@ for fpath, keys in [(agent_file, given_keys), (counterpart, counterpart_keys)]:
                 f"Add '## {slug}' entry to agents/sources.md or remove '{slug}' from {rel} source_keys."
             )
 
-# --- Checks 4, 5, 6: Per-slug checks in agents/sources.md ---
+# --- Checks 3, 4, 5: Per-slug checks in agents/sources.md ---
 for slug in parse_h2_slugs(sources_content):
-    # Check 4: Contributing files exist (paths relative to plugin root)
+    # Check 3: Contributing files exist (paths relative to plugin root)
     cf_value = parse_contributing_files(sources_content, slug)
     if cf_value and not cf_value.startswith("(none"):
         cf_files = [p.strip() for p in cf_value.split(",") if p.strip()]
@@ -241,7 +241,7 @@ for slug in parse_h2_slugs(sources_content):
                     f"Create '{cf_rel}' relative to the plugin root, or correct the path in agents/sources.md."
                 )
             else:
-                # Check 5: Bidirectional — file should list slug in its source_keys
+                # Check 4: Bidirectional — file should list slug in its source_keys
                 with open(cf_abs) as f:
                     cf_content = f.read()
                 cf_fm, _ = parse_frontmatter(cf_content)
@@ -254,7 +254,7 @@ for slug in parse_h2_slugs(sources_content):
                         f"Add '{slug}' to the top-level source_keys frontmatter in '{cf_rel}'."
                     )
 
-    # Check 6: Research doc field required
+    # Check 5: Research doc field required
     rd_value = parse_research_doc(sources_content, slug)
     if rd_value is None:
         emit_fail(

plugins/kyberforge/skills/agent-audit/scripts/validate.sh

@@ -11,7 +11,7 @@ Arguments:
   agent-file  Path to either the Claude Code .md or Copilot .agent.md agent file.
 
 Exit codes:
-  0  All checks passed
+  0  All checks passed (may include SUGGESTIONs)
   1  One or more checks failed
   2  Script error (unrecognized file extension or missing field-inventory.md)
 EOF
@@ -72,13 +72,23 @@ def parse_section_tokens(content, section_name):
     return set()
 
 cc_only_fields = parse_section_tokens(inv_content, 'claude-code-only-fields')
+copilot_only_fields = parse_section_tokens(inv_content, 'copilot-only-fields')
 plugin_ignored_fields = parse_section_tokens(inv_content, 'plugin-silently-ignored-fields')
 
+# Tools the runtime withholds from subagents regardless of the tools field
+SUBAGENT_UNAVAILABLE_TOOLS = {
+    'AskUserQuestion', 'EnterPlanMode', 'ExitPlanMode', 'ScheduleWakeup', 'WaitForMcpServers',
+}
+
+# Copilot body length limit (chars) — content beyond this is silently truncated
+COPILOT_BODY_LIMIT = 30000
+
 # --- Detect scope ---
 def detect_scope(start_dir):
     current = os.path.abspath(start_dir)
     while True:
-        if os.path.isfile(os.path.join(current, 'plugin.json')):
+        if (os.path.isfile(os.path.join(current, 'plugin.json')) or
+                os.path.isfile(os.path.join(current, '.claude-plugin', 'plugin.json'))):
             return 'plugin', current
         if os.path.isdir(os.path.join(current, '.git')):
             return 'project', current
@@ -116,12 +126,16 @@ else:  # user
 
 # --- Helpers ---
 failed = False
+suggestions = []
 
 def fail(msg):
     global failed
     failed = True
     print(f"FAIL  {msg}")
 
+def suggest(msg):
+    suggestions.append(msg)
+
 PLACEHOLDER_RE = re.compile(r'(?<!`)FILL IN:[^`\n]')
 
 def parse_frontmatter(content):
@@ -142,6 +156,17 @@ def get_frontmatter_keys(fm):
             keys.add(m.group(1))
     return keys
 
+def extract_tools_list(fm):
+    """Extract tool names from the tools frontmatter field (space or comma separated)."""
+    val = extract_field(fm, 'tools')
+    if not val:
+        return set()
+    return set(re.split(r'[\s,]+', val.strip()))
+
+def is_copilot_cloud_ide(fpath):
+    """True if the file is a cloud/IDE Copilot agent (name is optional for these)."""
+    return '.github/copilot/agents' in os.path.abspath(fpath).replace(os.sep, '/')
+
 def check_file(fpath, file_provider, is_plugin_scope):
     local_fname = os.path.basename(fpath)
     with open(fpath) as f:
@@ -152,20 +177,23 @@ def check_file(fpath, file_provider, is_plugin_scope):
         fail(f"no valid YAML frontmatter (---...---) — {local_fname}")
         return
 
-    # name
+    # name — required for CC and Copilot CLI; optional for Copilot cloud/IDE agents
+    cloud_ide = (file_provider == 'copilot' and is_copilot_cloud_ide(fpath))
     name_val = extract_field(fm, 'name')
+    if not cloud_ide:
         if not name_val:
             fail(f"name field is missing or empty — {local_fname}")
         else:
             if not re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name_val):
                 fail(f"name '{name_val}' is not kebab-case — {local_fname}")
-        # stem check
+            # Stem check applies to Copilot CLI only; CC docs say filename need not match name
             if file_provider == 'copilot':
                 stem = local_fname[:-len('.agent.md')]
-        else:
-            stem = local_fname[:-len('.md')]
                 if name_val != stem:
                     fail(f"name '{name_val}' does not match filename stem '{stem}' — {local_fname}")
+    elif name_val and not re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name_val):
+        # cloud/IDE: name is optional, but if present it must be valid
+        fail(f"name '{name_val}' is not kebab-case — {local_fname}")
 
     # description
     desc_val = extract_field(fm, 'description')
@@ -181,6 +209,9 @@ def check_file(fpath, file_provider, is_plugin_scope):
     else:
         if PLACEHOLDER_RE.search(body):
             fail(f"body contains unfilled FILL IN: placeholder — {local_fname}")
+        # Copilot body length limit
+        if file_provider == 'copilot' and len(body) > COPILOT_BODY_LIMIT:
+            suggest(f"body exceeds {COPILOT_BODY_LIMIT:,} characters ({len(body):,} chars) — content beyond the limit is silently truncated by the Copilot runtime — {local_fname}")
 
     # CC-only fields in Copilot file
     if file_provider == 'copilot':
@@ -189,6 +220,13 @@ def check_file(fpath, file_provider, is_plugin_scope):
             if key in cc_only_fields:
                 fail(f"CC-only field '{key}' present in Copilot file — {local_fname}")
 
+    # Copilot-only fields in CC file
+    if file_provider == 'claude-code':
+        fm_keys = get_frontmatter_keys(fm)
+        for key in sorted(fm_keys):
+            if key in copilot_only_fields:
+                fail(f"Copilot-only field '{key}' present in CC file — {local_fname}")
+
     # Silently-ignored fields in plugin-scope CC file
     if file_provider == 'claude-code' and is_plugin_scope:
         fm_keys = get_frontmatter_keys(fm)
@@ -196,6 +234,12 @@ def check_file(fpath, file_provider, is_plugin_scope):
             if key in plugin_ignored_fields:
                 fail(f"plugin-silently-ignored field '{key}' present in plugin-scope CC file — {local_fname}")
 
+    # Subagent-unavailable tools listed in tools field
+    tools = extract_tools_list(fm)
+    unavailable = tools & SUBAGENT_UNAVAILABLE_TOOLS
+    for tool in sorted(unavailable):
+        suggest(f"'{tool}' is listed in tools but is never available to subagents — the runtime withholds it regardless — {local_fname}")
+
 # --- Check counterpart exists ---
 if not os.path.isfile(counterpart):
     fail(f"counterpart file not found: {counterpart}")
@@ -206,5 +250,8 @@ is_plugin = (scope == 'plugin')
 check_file(agent_file, provider, is_plugin)
 check_file(counterpart, counterpart_provider, is_plugin)
 
+for s in suggestions:
+    print(f"SUGGESTION  {s}")
+
 sys.exit(1 if failed else 0)
 PYTHON

plugins/kyberforge/skills/agent-audit/tests/validate.bats

@@ -200,7 +200,7 @@ EOF
 @test "fails when frontmatter name does not match filename stem" {
     local dir="$TMPDIR/agents"
     make_plugin_pair "$dir" "my-agent"
-    cat > "$dir/my-agent.md" <<EOF
+    cat > "$dir/my-agent.agent.md" <<EOF
 ---
 name: wrong-name
 description: A valid agent description.

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

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

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

@@ -28,17 +28,17 @@ 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.
 - Copilot has no `permissionMode`, `maxTurns`, `isolation`, or `memory` fields — do not include them in the Copilot file.
 - `model` resolution order for Claude Code: `CLAUDE_CODE_SUBAGENT_MODEL` env var → per-invocation parameter → frontmatter `model` → main session model. The frontmatter value is a low-priority default, not a guarantee.
 
-If the destination is a plugin directory, read `references/deployment-modes.md`.
-
 ## Route
 
+If the destination is a plugin directory, read `references/deployment-modes.md`.
+
 Determine which flow before touching the filesystem:
 
 - **Neither `<name>.md` nor `<name>.agent.md` exist at the target paths** → follow **Creating a new agent**
@@ -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:
@@ -75,8 +77,8 @@ bash scripts/new-agent.sh security-reviewer ~
 ```
 
 **Scope detection (script handles this automatically):**
-- Root contains `plugin.json` → plugin scope → creates `<root>/agents/<name>.md` + `<root>/agents/<name>.agent.md`
-- Root is a project directory (no `plugin.json`) → creates `<root>/.claude/agents/<name>.md` + `<root>/.github/agents/<name>.agent.md`
+- Root contains `plugin.json`, `.claude-plugin/plugin.json`, `.plugin/plugin.json`, or `.github/plugin/plugin.json` → plugin scope → creates `<root>/agents/<name>.md` + `<root>/agents/<name>.agent.md`
+- Root is a project directory (no plugin marker) → creates `<root>/.claude/agents/<name>.md` + `<root>/.github/agents/<name>.agent.md`
 - Root is `~` → creates `~/.claude/agents/<name>.md` + `~/.copilot/agents/<name>.agent.md`
 
 The script is file-by-file no-op — it skips any file that already exists.
@@ -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.

plugins/kyberforge/skills/agent-author/assets/README.md

@@ -5,4 +5,4 @@
 Annotated agent definition templates copied by `scripts/new-agent.sh` when scaffolding a new agent.
 
 - **`claude-code.md`** — Claude Code agent definition template. Includes all supported frontmatter fields (required and optional) with inline guidance comments and `FILL IN:` placeholders. Notes which fields are silently ignored for plugin agents.
-- **`copilot.agent.md`** — Copilot CLI agent definition template. Uses Copilot-specific fields (`target`, `user-invocable`, `disable-model-invocation`, Copilot tool aliases). Explicitly excludes Claude Code-only fields.
+- **`copilot.agent.md`** — Copilot CLI agent definition template (CLI format). Excludes cloud/IDE-only fields (`target`, `user-invocable`, `disable-model-invocation`, `mcp-servers`) and Claude Code-only fields. Uses Copilot tool aliases (`execute`, `read`, `edit`, `search`, `agent`, `web`).

plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md

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

plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md

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

plugins/kyberforge/skills/agent-author/references/README.md

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

plugins/kyberforge/skills/agent-author/references/deployment-modes.md

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

plugins/kyberforge/skills/agent-author/references/scripts.md

@@ -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`, `.claude-plugin/plugin.json`, `.plugin/plugin.json`, or `.github/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.

plugins/kyberforge/skills/agent-author/references/sources.md

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

plugins/kyberforge/skills/skill-author/README.md

@@ -4,7 +4,7 @@ Author and refine skills conforming to the [agentskills.io](https://agentskills.
 
 ## What it does
 
-Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, if the skill lives inside a plugin directory, bumps the plugin version in both manifests.
+Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's `metadata.version` when present (minor for create, patch for improve).
 
 ## Before you start
 

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

@@ -2,12 +2,12 @@
 name: skill-author
 description: >
   Use when the user wants to create a new skill from scratch ("write a skill
-  for X", "build a skill that does Y", "create a SKILL.md for Z"), or improve
+  for X", "build a skill that does Y", "create a SKILL.md for Z") or improve
   an existing one ("improve this skill", "fix based on feedback", "apply these
-  audit findings", "update based on grill output"). Also use when the user
-  provides inline feedback about a skill's behavior and wants it applied, or
-  when a grill session, eval run, or audit has produced findings the user wants
-  acted on — even if they don't say "improve" explicitly. Do not use for read-only review — use
+  audit findings", "update based on grill output"). Also use when the user provides inline feedback
+  about a skill's behavior and wants it applied, or when a grill session, eval
+  run, or audit has produced findings the user wants acted on — even if they
+  don't say "improve" explicitly. Do not use for read-only review — use
   /skill-audit instead. Do not use to author agent definition files.
 allowed-tools: Bash Read Write Edit
 metadata:
@@ -92,9 +92,17 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
 **Optional fields** — uncomment and fill in or remove entirely:
 - `license` — include when distributing the skill externally
 - `compatibility` — include if the skill requires specific tools, runtimes, or network access (max 500 characters)
-- `metadata` — key-value map; use `author`, `version`, `category`
+- `metadata` — key-value map; use `author`, `version`, `category`; add `source_keys` now (see below) if research sources are in context
 - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client)
 
+**`metadata.source_keys`** — if research sources are in context, list the relevant slugs here as you write the body; don't defer this to Step 5. Agents that fill in source_keys late tend to omit it entirely. Example:
+```yaml
+metadata:
+  source_keys:
+    - my-source-slug
+    - another-slug
+```
+
 **Body — include only what the agent lacks**
 
 Rename the placeholder section heading to one that fits the skill's structure — `## Step 1`, `## Workflow`, `## Instructions`, etc.
@@ -200,10 +208,18 @@ If no research `sources.md` is in context, delete `references/sources.md`.
 
 ### Step 6 — Validate and close
 
+Before running the audit, confirm:
+- [ ] Skill name matches the directory name exactly
+- [ ] `description` field is present and non-empty
+- [ ] Body has at least one non-empty section
+- [ ] No `FILL IN:` placeholders remain in any file
+
 Run `/skill-audit` on `<destination-dir>/<skill-name>`.
 
 All FAIL findings must be resolved before the skill is considered done.
 
+If the skill is versioned (`metadata.version`), set it to the next **minor** version (e.g. `0.2.0` → `0.3.0`). New skills without a prior version start at `0.1.0`.
+
 ## Improving an existing skill
 
 ### Step 1 — Verify inputs
@@ -258,4 +274,11 @@ If a signal points to a script or reference file, edit that file directly rather
 
 ### Step 5 — Validate and close
 
+Before running the audit, confirm:
+- [ ] Skill name still matches the directory name
+- [ ] No `FILL IN:` placeholders were introduced
+- [ ] No previously-passing audit checks were broken by the edits
+
 Run `/skill-audit` on the skill directory. Resolve any FAIL findings before considering the improvement complete.
+
+If the skill is versioned (`metadata.version`), bump the **patch** version (e.g. `0.1.0` → `0.1.1`).

plugins/kyberforge/skills/skill-author/references/sources.md

@@ -1,3 +1,14 @@
+---
+source_keys:
+  - agentskills-home
+  - agentskills-spec
+  - agentskills-best-practices
+  - agentskills-optimizing-descriptions
+  - agentskills-evaluating-skills
+  - agentskills-using-scripts
+  - agentskills-quickstart
+---
+
 # Sources
 
 <!-- agentskills.io/llms.txt was used for initial source discovery and is not listed below; it contributed no skill file content directly. -->