feat(kyberforge): add forge routing skill for factory artifact classification

Grills intent, classifies target artifact type (skill/agent/plugin/marketplace
entry) against a fully descriptive table, then routes to the matching author
skill via fork subagent (falling back to inline when fork is unavailable or
the flow needs live interaction). Adds an independent clean-context audit
recheck after each skill/agent route, looping author-then-audit until the
recheck comes back clean, since the author skill's own inline audit shares
context with the work it verifies. Updates CONTEXT.md's Skill composition
entry to describe this recheck loop and adds forge's provenance chain
(references/sources.md).

Refs Defame1297/holocron#61

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.claude/settings.json

@@ -1,6 +1,8 @@
 {
   "enabledPlugins": {
     "bin@holocron": true,
+    "core@holocron": true,
+    "git@holocron": true,
     "kyberforge@holocron": true
   },
   "hooks": {

CONTEXT.md

@@ -49,7 +49,7 @@ The provider-agnostic always-on instruction entry point. Two files:
 Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0012.
 
 ### Skill composition
-A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology.
+A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`.
 
 ### Provider-agnostic issue tracker
 Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it).

plugins/kyberforge/docs/research/docs/agentskillsio/overview.md

@@ -4,6 +4,7 @@ source_keys:
   - agentskills-home
   - agentskills-spec
   - agentskills-quickstart
+  - agentskills-best-practices
 ---
 
 ## What Agent Skills is
@@ -30,6 +31,10 @@ Agents load skills in three stages:
 
 Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint.
 
+## Scope: no concept of "agent"
+
+The spec is runtime-agnostic and defines only the skill format — it does not define "agent," "subagent," or any delegation/orchestration concept, and neither the specification nor the best-practices guide contains criteria for choosing a skill over a separate agent process. Skill-vs-agent selection is a decision made by whichever runtime consumes the skill (see the Claude Code and GitHub Copilot decision-criteria docs for their respective answers), not something the Agent Skills format itself addresses.
+
 ## Canonical directory
 
 The canonical location for skills is `.agents/skills/` at the project root. Tool-specific locations (`.claude/skills/` for Claude Code, `~/.codex/skills/` for Codex) are thin adapters that map to this canonical path. Putting skills at `.agents/skills/` maximizes cross-tool portability.

plugins/kyberforge/docs/research/docs/claude-code-plugins/decision-criteria.md

@@ -0,0 +1,33 @@
+---
+topic: decision-criteria
+source_keys:
+  - context7-websites-code-claude
+---
+
+## Skill vs Subagent
+
+Official comparison (`Compare similar features > Skill vs Subagent`): skills add to the main context window and are best for reference material or invocable workflows; subagents use a separate context window with their own input/output tokens, making them ideal for tasks that read many files, run in parallel, or need a specialized worker — especially when the main context window is getting full.
+
+Restated: skills are reusable content (instructions, knowledge, workflows) loaded into any context, benefiting from content sharing across the conversation. Subagents are isolated workers with their own context, designed for context isolation — work happens separately and only a summary returns to the main conversation.
+
+## Combining skills and subagents
+
+The two are not mutually exclusive — Claude Code documents two explicit combination mechanisms, inverses of each other:
+
+- **`skills:` field on a subagent** — preloads specific skill content into that subagent's own system prompt. The subagent controls the prompt; skill content is injected into it at startup.
+- **`context: fork` field on a skill** — runs the skill's own body in an isolated agent context instead of the calling conversation. The `agent` field selects which subagent type executes it (built-in `Explore`, `Plan`, `general-purpose`, or a custom subagent); defaults to `general-purpose` if omitted. The skill's content becomes the task prompt injected into that agent.
+
+```yaml
+---
+name: deep-research
+description: Research a topic thoroughly
+context: fork
+agent: Explore
+---
+Research $ARGUMENTS thoroughly:
+1. Find relevant files using Glob and Grep
+2. Read and analyze the code
+3. Summarize findings with specific file references
+```
+
+This means a single skill file can declare that it should always execute in isolation, without needing a separate agent definition file — useful when the isolation need is inherent to the task (e.g., broad file search) rather than something the caller decides per-invocation.

plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md

@@ -3,8 +3,8 @@
 ## context7-websites-code-claude
 
 - **URL:** context7:/websites/code_claude
-- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format, plugin update lifecycle, interactive plugin manager UI, private marketplace authentication, `commands` vs `skills/` distinction
+- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format, plugin update lifecycle, interactive plugin manager UI, private marketplace authentication, `commands` vs `skills/` distinction, skill-vs-subagent decision guidance and combination mechanisms (`skills:` field, `context: fork`)
-- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md, installation.md
+- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md, installation.md, decision-criteria.md
 - **Status:** `extracted`
 
 ## claude-code-plugins-docs

plugins/kyberforge/docs/research/docs/github-copilot-plugins/decision-criteria.md

@@ -0,0 +1,26 @@
+---
+topic: decision-criteria
+source_keys:
+  - context7-github-en-copilot
+---
+
+## Skill vs custom agent vs subagent
+
+GitHub's own framing: "Skills enable Copilot to perform specialized tasks, while custom agents enhance Copilot with assistance tailored to your specific needs."
+
+The CLI features comparison doc is more concrete about when *not* to use each:
+
+- **Avoid a custom agent** if you only need guidance text — a skill is the lighter-weight solution — or if the default agent already performs the task well and no specialization is needed.
+- **Avoid a skill** when the guidance should apply universally (use custom instructions instead), or when the task needs new capabilities rather than more guidance — that calls for an MCP server or a custom agent.
+
+The customization cheat sheet draws a three-way distinction:
+
+| Primitive | Best fit | Trigger |
+|---|---|---|
+| Custom agent | Projects/processes with distinct stages needing specialized capabilities or strict handoffs | Manual — selected from a dropdown |
+| Subagent | Complex subtasks that must run isolated from the main agent | Automatic or by direct prompt reference |
+| Agent skill | Multi-step workflows with bundled assets (scripts, references, templates) | Automatic — Copilot matches it to the prompt when relevant (e.g. debugging GitHub Actions failures) |
+
+Custom agents and subagents both isolate context and restrict tools, but differ in invocation: custom agents are a deliberate, user-selected mode switch; subagents are spawned automatically mid-task to offload work without cluttering the main agent's context (confirmed by the SDK example pattern of excluding a `heavyContextTool` from the default agent and giving it only to a dedicated `researcher` custom agent, "so the default agent remains clean").
+
+Skills vs. custom instructions (a related but separate boundary): use custom instructions for general information like coding standards; use skills for detailed instructions Copilot should only access when relevant to the specific task.

plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md

@@ -3,8 +3,8 @@
 ## context7-github-en-copilot
 
 - **URL:** context7:/websites/github_en_copilot
-- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, and marketplace
+- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, marketplace, and skill-vs-agent-vs-subagent decision guidance
-- **Contributing files:** overview.md, agent-definition.md, configuration.md, installation.md, marketplace.md, api-reference.md, examples.md, sdk.md
+- **Contributing files:** overview.md, agent-definition.md, configuration.md, installation.md, marketplace.md, api-reference.md, examples.md, sdk.md, decision-criteria.md
 - **Status:** `extracted`
 
 ## github-custom-agents-configuration

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

@@ -56,6 +56,11 @@ If a description finding is borderline, read `references/description-quality.md`
 - 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
 
+**Body/Frontmatter comments:**
+- Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding.
+- Look for patterns like `# Optional. <long explanation>` or extensive inline guidance (more than 1–2 lines per field) that should be condensed or removed before shipping.
+- This mirrors skill-audit's body-discipline check but applies to template documentation in the frontmatter — template guidance belongs in development; agent-ready files should have minimal comments.
+
 **Pair consistency (cross-file):**
 - 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
@@ -65,7 +70,7 @@ If a description finding is borderline, read `references/description-quality.md`
 Open with a coverage line:
 
 ```text
-Checked: structure · provider-safety · description · body · pair-consistency · provenance
+Checked: structure · provider-safety · description · body · comment-discipline · pair-consistency · provenance
 ```
 
 Then output only dimensions that have findings, grouped under H3 headings, FAILs before SUGGESTIONs within each dimension. Omit clean dimensions entirely. `### Provenance` findings are sourced verbatim from `validate-provenance.sh` output — copy them without rephrasing.

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

@@ -85,7 +85,7 @@ The script is file-by-file no-op — it skips any file that already exists.
 
 ### Step 2 — Fill in the Claude Code agent file (`<name>.md`)
 
-Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder.
+Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder. **Remove all template documentation comments from the YAML frontmatter after filling in required fields** — these are marked with `<!--` and `-->` and must be deleted before shipping.
 
 **`name`** — lowercase letters and hyphens only. Must be unique within the scope.
 
@@ -141,6 +141,8 @@ There are **two distinct Copilot agent formats** with different paths and field
 
 **`source_keys`** — add the same top-level list as the CC file when research sources were used. Omit when no research was used.
 
+**Remove all template documentation comments from the YAML frontmatter after filling in required fields** — these are marked with `<!--` and `-->` and must be deleted before shipping.
+
 The system prompt body should match the Claude Code version — the agent's task definition is the same across providers.
 
 ### Step 4 — Populate or delete `agents/sources.md` (plugin scope only)

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

@@ -1,71 +1,72 @@
 ---
-# Claude Code agent definition
+<!-- Claude Code agent definition
-# Fill in all FILL IN: placeholders. Remove or uncomment optional fields as needed.
+     Fill in all FILL IN: placeholders. Remove or uncomment optional fields as needed.
+     Delete template comments before shipping. -->
 
 name: AGENT_NAME
-# Required. Lowercase letters and hyphens only. Must be unique within the scope.
+<!-- Required. Lowercase letters and hyphens only. Must be unique within the scope.
-# Duplicate names are silently discarded — no warning is emitted.
+     Duplicate names are silently discarded — no warning is emitted. -->
 
 description: FILL IN: Action-first description of what this agent does and when to invoke it.
-# Required. The primary signal for autonomous delegation.
+<!-- Required. The primary signal for autonomous delegation.
-# Start with a verb: "Reviews...", "Analyzes...", "Generates..."
+     Start with a verb: "Reviews...", "Analyzes...", "Generates..."
-# Include "Use proactively" to trigger automatic invocation.
+     Include "Use proactively" to trigger automatic invocation.
-# Be specific about the triggering condition and domain.
+     Be specific about the triggering condition and domain.
-# Example: "Reviews pull request diffs for security issues. Use proactively after code changes."
+     Example: "Reviews pull request diffs for security issues. Use proactively after code changes." -->
 
-# tools: Read Bash Grep
+<!-- tools: Read Bash Grep
-# Optional. Space-separated allowlist. Omit to inherit all tools from parent.
+     Optional. Space-separated allowlist. Omit to inherit all tools from parent.
-# Use Agent(type1,type2) to restrict which subagent types this agent can spawn.
+     Use Agent(type1,type2) to restrict which subagent types this agent can spawn.
-# Omit Agent entirely to prevent this agent from spawning subagents.
+     Omit Agent entirely to prevent this agent from spawning subagents.
-# Never available to subagents regardless of tools field:
+     Never available to subagents regardless of tools field:
-#   AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers
+       AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers
-# Exception: ExitPlanMode IS available when parent session runs in permissionMode: plan
+     Exception: ExitPlanMode IS available when parent session runs in permissionMode: plan -->
 
-# model: sonnet
+<!-- model: sonnet
-# Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID.
+     Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID.
-# Omit to inherit from the main session.
+     Omit to inherit from the main session.
-# Resolution order: CLAUDE_CODE_SUBAGENT_MODEL env var → per-invocation param → this field → session model.
+     Resolution order: CLAUDE_CODE_SUBAGENT_MODEL env var → per-invocation param → this field → session model. -->
 
-# effort: medium
+<!-- effort: medium
-# Optional. low / medium / high / xhigh / max. Overrides session effort level for this agent.
+     Optional. low / medium / high / xhigh / max. Overrides session effort level for this agent. -->
 
-# maxTurns: 20
+<!-- maxTurns: 20
-# Optional. Integer cap on agentic turns. Prevents runaway on bounded tasks.
+     Optional. Integer cap on agentic turns. Prevents runaway on bounded tasks. -->
 
-# memory: project
+<!-- memory: project
-# Optional. user / project / local. Enables cross-session MEMORY.md (first 200 lines loaded at startup).
+     Optional. user / project / local. Enables cross-session MEMORY.md (first 200 lines loaded at startup).
-# Auto-enables Read/Write/Edit tools.
+     Auto-enables Read/Write/Edit tools. -->
 
-# isolation: worktree
+<!-- isolation: worktree
-# Optional. Set to "worktree" to run in an isolated temporary git worktree.
+     Optional. Set to "worktree" to run in an isolated temporary git worktree.
-# Auto-cleaned if no changes are made.
+     Auto-cleaned if no changes are made. -->
 
-# color: blue
+<!-- color: blue
-# Optional. UI color: red, blue, green, yellow, purple, orange, pink, cyan.
+     Optional. UI color: red, blue, green, yellow, purple, orange, pink, cyan. -->
 
-# background: false
+<!-- background: false
-# Optional. Set true to force background execution.
+     Optional. Set true to force background execution. -->
 
-# disallowedTools: mcp__filesystem__write_file
+<!-- disallowedTools: mcp__filesystem__write_file
-# Optional. Space-separated denylist, applied before the tools allowlist.
+     Optional. Space-separated denylist, applied before the tools allowlist.
-# Supports mcp__* glob patterns (e.g. mcp__filesystem__* to block all filesystem tools).
+     Supports mcp__* glob patterns (e.g. mcp__filesystem__* to block all filesystem tools). -->
 
-# skills:
+<!-- skills:
-#   - skill-name
+       - skill-name
-# Optional. Skill names preloaded into this agent's context at startup.
+     Optional. Skill names preloaded into this agent's context at startup.
-# Different from the source_keys metadata field (which is provenance-only).
+     Different from the source_keys metadata field (which is provenance-only). -->
 
-# initialPrompt: "Start by reading the README."
+<!-- initialPrompt: "Start by reading the README."
-# Optional. Auto-submitted as the first turn when this agent activates as the main session thread.
+     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.
+     Only set when this agent is intended for main-thread (not subagent) activation. -->
 
-# source_keys:
+<!-- source_keys:
-#   - slug-name
+       - slug-name
-# Development-only. Add when research sources informed this agent (slugs must match agents/sources.md).
+     Development-only. Add when research sources informed this agent (slugs must match agents/sources.md).
-# Omit when no research was used. Not a runtime field — silently ignored by Claude Code.
+     Omit when no research was used. Not a runtime field — silently ignored by Claude Code. -->
 
-# NOTE: hooks, mcpServers, and permissionMode are silently ignored for plugin agents.
+<!-- NOTE: hooks, mcpServers, and permissionMode are silently ignored for plugin agents.
-# Those fields only work in .claude/agents/ or ~/.claude/agents/.
+     Those fields only work in .claude/agents/ or ~/.claude/agents/. -->
 ---
 
 FILL IN: System prompt body. Write as a direct role instruction.

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

@@ -1,44 +1,45 @@
 ---
-# GitHub Copilot CLI agent definition (CLI format — path: .github/agents/<name>.agent.md)
+<!-- 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.
+     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.
+     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.
+     Body length limit: 30,000 characters — content beyond this is silently truncated.
-#
+     Delete template comments before shipping.
-# NOTE: This template is for the CLI format. The cloud/IDE format (path: .github/copilot/agents/<name>.md,
+
-# extension: .md) supports additional fields: target, user-invocable, disable-model-invocation, mcp-servers.
+     NOTE: This template is for the CLI format. The cloud/IDE format (path: .github/copilot/agents/<name>.md,
-# Do not add those fields here — they are silently ignored by the CLI runtime.
+     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.
+<!-- Required. Kebab-case identifier. Home-directory version wins on name collision. -->
 
 description: FILL IN: Action-first description of what this agent does and when to invoke it.
-# Required. Used by the runtime for automatic agent selection — quality matters.
+<!-- Required. Used by the runtime for automatic agent selection — quality matters.
-# Start with a verb: "Reviews...", "Analyzes...", "Generates..."
+     Start with a verb: "Reviews...", "Analyzes...", "Generates..."
-# Example: "Reviews pull request diffs for security issues."
+     Example: "Reviews pull request diffs for security issues." -->
 
-# tools: ["read", "search", "edit"]
+<!-- tools: ["read", "search", "edit"]
-# Optional. Array of tool names. Omit = all available tools. [] = no tools.
+     Optional. Array of tool names. Omit = all available tools. [] = no tools.
-# Copilot tool aliases (use these, not Claude Code names):
+     Copilot tool aliases (use these, not Claude Code names):
-#   execute   — run shell commands (aliases: shell, Bash, powershell)
+       execute   — run shell commands (aliases: shell, Bash, powershell)
-#   read      — read file contents (aliases: Read, NotebookRead)
+       read      — read file contents (aliases: Read, NotebookRead)
-#   edit      — modify files (aliases: Edit, MultiEdit, Write, NotebookEdit)
+       edit      — modify files (aliases: Edit, MultiEdit, Write, NotebookEdit)
-#   search    — search files (aliases: Grep, Glob)
+       search    — search files (aliases: Grep, Glob)
-#   agent     — invoke sub-agents (aliases: custom-agent, Task)
+       agent     — invoke sub-agents (aliases: custom-agent, Task)
-#   web       — web search and fetch (aliases: WebSearch, WebFetch)
+       web       — web search and fetch (aliases: WebSearch, WebFetch)
-# For MCP tools: "server-name/tool-name" or "server-name/*"
+     For MCP tools: "server-name/tool-name" or "server-name/*" -->
 
-# model: claude-sonnet-4-5
+<!-- model: claude-sonnet-4-5
-# Optional. Model to run this agent on.
+     Optional. Model to run this agent on.
-# Cloud/IDE-only fields (target, user-invocable, disable-model-invocation, mcp-servers)
+     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.
+     are not valid in this CLI format — use the .github/copilot/agents/<name>.md path for those. -->
 
-# source_keys:
+<!-- source_keys:
-#   - slug-name
+       - slug-name
-# Development-only. Add when research sources informed this agent (slugs must match agents/sources.md).
+     Development-only. Add when research sources informed this agent (slugs must match agents/sources.md).
-# Omit when no research was used. Not a Copilot runtime field — silently ignored.
+     Omit when no research was used. Not a Copilot runtime field — silently ignored. -->
 
-# DO NOT include these Claude Code-only fields:
+<!-- DO NOT include these Claude Code-only fields:
-#   maxTurns, isolation, memory, permissionMode, effort, hooks, mcpServers
+       maxTurns, isolation, memory, permissionMode, effort, hooks, mcpServers -->
 ---
 
 FILL IN: System prompt body. Should match the Claude Code version — the agent's task is the same across providers.

plugins/kyberforge/skills/forge/README.md

@@ -0,0 +1,37 @@
+# forge
+
+Guided entry point for building or improving something in kyberforge when the target artifact type isn't decided yet.
+
+## What it does
+
+Grills the user's intent via `bin:grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types.
+
+Author-skill invocation defaults to a fork subagent (inherits the grilled-intent context) and falls back to inline when forking isn't possible or the routed flow needs live user interaction (clarifying questions, a HITL gate). After a `skill-author` or `agent-author` route finishes — each already closes out with its own inline audit — forge spins up a separate clean-context subagent to independently re-run the matching audit skill (`skill-audit` / `agent-audit`) as a distinct check on the finished artifact, not a duplicate of the inline one. If that clean audit turns up any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved. `plugin-author` and `marketplace-author` routes get no recheck: they have no audit counterpart, and their real terminal check (`claude plugin validate`) is already part of their own flow.
+
+## Before you start
+
+Have a rough idea of what you want to build or change. forge doesn't require you to already know whether it's a skill, agent, plugin, or marketplace entry — that classification is its job.
+
+## Usage
+
+```
+/forge
+```
+
+Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, `/plugin-author`, `/marketplace-author`) when you already know the artifact type.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/sources.md` | Provenance chain — research sources that informed this skill |
+
+## Routes to
+
+| Artifact type | Skill |
+|---|---|
+| Skill | `kyberforge:skill-author` |
+| Agent / subagent definition | `kyberforge:agent-author` |
+| Plugin | `kyberforge:plugin-author` |
+| Marketplace entry | `kyberforge:marketplace-author` |

plugins/kyberforge/skills/forge/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: forge
+description: >
+  Use when the user wants to build, add, or improve something
+  but hasn't yet named which of it (skill, agent, plugin, or marketplace
+  entry) they need — "I want to add something to kyberforge", "not sure if
+  this should be a skill or a plugin", "help me figure out what to build",
+  "I have an idea but don't know where it belongs". Grills the intent first,
+  classifies the target artifact type, then routes to the matching author
+  skill. Do not use when the user already names the target artifact type or
+  skill/agent explicitly (e.g. "run /skill-author on my-skill", "create an
+  agent for X") — route directly to that author skill instead, bypassing
+  forge.
+metadata:
+  category: factory
+  source_keys:
+    - claude-code-subagents-docs
+    - context7-websites-code-claude
+    - agentskills-spec
+---
+
+## Gotchas
+
+- forge is an optional guided entry point, not a gate — the six existing factory skills (`skill-author`, `skill-audit`, `agent-author`, `agent-audit`, `plugin-author`, `marketplace-author`) remain directly invokable and forge does not intercept those calls.
+- Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite sharing a name — `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. Keep this straight when deciding how to invoke a subagent in Step 3.
+
+## Step 1 — Grill the intent
+
+Call `bin:grill-with-docs` unless a grill session was already performed and is available in the context.
+Grilling may surface that the artifact type assumed at the start is wrong, or that the idea splits into more than one artifact.
+This step always runs inline, in the current conversation — grilling is interactive and a subagent cannot hold the back-and-forth.
+
+## Step 2 — Classify the artifact type
+
+Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans several):
+
+| Intent                                                                                                                                                                                                                               | Artifact type               | Route to                        |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -----------------------------| ---------------------------------|
+| A reusable capability or workflow the agent should load inline in the main conversation — triggered automatically by description-matching, not a fresh context, and free to bundle its own `references/`, `scripts/`, or `assets/`   | Skill                       | `kyberforge:skill-author`       |
+| A recurring task needs its own reusable agent/subagent definition — dedicated system prompt, tools, and description, invokable by name across sessions                                                                               | Agent / subagent definition | `kyberforge:agent-author`       |
+| A new distributable unit is needed — no existing plugin is the right home for the skill/agent/hook/MCP server being built, or the bundle needs its own manifest, versioning, and install lifecycle separate from what already exists | Plugin                      | `kyberforge:plugin-author`      |
+| The plugin itself already exists (or was just created) and only its marketplace-facing metadata needs to change — listing it for the first time, or updating its version/description entry — never the plugin's contents             | Marketplace entry           | `kyberforge:marketplace-author` |
+
+If the intent is genuinely ambiguous between rows even after grilling, ask the user directly rather than guessing.
+
+This table classifies what to build, not how to run it — a one-off task that merely needs an isolated vs. context-inheriting run (rather than a new, reusable definition) isn't an artifact at all; there's nothing here to route it to.
+
+## Step 3 — Announce, then route
+
+State the classification and which skill(s) will run before invoking anything.
+
+**Invoking the author skill(s).** Default to a fork subagent — it inherits the full grilled-intent conversation, so the author skill doesn't need to be re-briefed. Fall back to an inline invocation (same conversation, no subagent) when either is true:
+- **Fork is technically unavailable** — already running inside a fork (a fork cannot spawn another fork), a nesting-depth cap is reached, or the environment doesn't support forking.
+- **The routed flow needs live user interaction mid-run** that a backgrounded fork can't surface in real time — clarifying questions, confirmation checkpoints, or a HITL gate (e.g. `plugin-author`'s release step). Judge this from context: if nothing about the routed flow signals a live checkpoint, prefer the fork subagent.
+
+`plugin-author` and `marketplace-author` routes always run inline — their flows are short, prompt-heavy, or gated, and get no follow-up audit-recheck step to justify running detached (see below).
+
+**After a skill or agent route finishes.** `skill-author` and `agent-author` already close out with their own inline audit (`skill-author` runs `/skill-audit`, `agent-author` invokes `kyberforge:agent-audit` directly) in the same context as the authoring work — that's unchanged. Once that author skill's run has finished, spin up a separate **clean-context subagent** (fresh, not forked, no inherited context) to independently re-run the same audit skill against the finished artifact. This is a distinct verification layer, not a duplicate: the inline audit shares context with the work it's checking and can share its blind spots, while the clean rerun has no stake in the result.
+
+If the clean audit surfaces any unresolved finding — not only a disagreement with the inline pass, any actionable finding on its own — loop: re-invoke the author skill (same fork-vs-inline judgment as the initial invocation) to resolve it, then re-run the clean audit again. Repeat until the clean audit comes back with nothing unresolved. Only then is the route done — the same resolve-before-close discipline `skill-author`/`agent-author` already apply to their own inline audit.
+
+When the intent spans multiple artifact types (e.g. a new skill inside a new plugin, then registering that plugin via `kyberforge:marketplace-author`), chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first (e.g. `plugin-author` creates the plugin directory before `skill-author` scaffolds a skill inside it).

plugins/kyberforge/skills/forge/references/sources.md

@@ -0,0 +1,81 @@
+# Sources
+
+## claude-code-subagents-docs
+
+- **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. Grounds Step 3's fork-vs-inline invocation logic: fork inherits full conversation history via `/fork` or `subagent_type: "fork"`, is not a declarable frontmatter field on any agent definition, cannot be nested (a fork cannot spawn another fork), and is a caller-side invocation choice rather than a property of the artifact being routed to.
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## context7-websites-code-claude
+
+- **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 — confirms the `context: fork` skill-level frontmatter field means isolated/fresh execution, the opposite of what the `/fork` subagent command does (inherits conversation). Informs the Gotchas entry warning against conflating the two.
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## claude-code-plugins-docs
+
+- **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. Background context for Step 2's plugin/marketplace rows; no forge-specific content drawn directly from it beyond that.
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## agentskills-spec
+
+- **URL:** https://agentskills.io/specification.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category. forge has none of that bulk, so a lean SKILL.md-plus-provenance-file shape is spec-legitimate; the `references/sources.md` in this directory exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-home
+
+- **URL:** https://agentskills.io/home.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** Agent Skills overview — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc.
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## agentskills-best-practices
+
+- **URL:** https://agentskills.io/skill-creation/best-practices.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** Best practices for skill creators — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc.
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## agentskills-optimizing-descriptions
+
+- **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** How to test and improve skill descriptions for triggering accuracy — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc.
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## agentskills-evaluating-skills
+
+- **URL:** https://agentskills.io/skill-creation/evaluating-skills.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** Eval-driven skill quality improvement — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc.
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## agentskills-using-scripts
+
+- **URL:** https://agentskills.io/skill-creation/using-scripts.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** Using scripts in skills — not applicable to forge (no scripts/ directory); listed for provenance completeness against the agentskillsio research doc.
+- **Contributing files:** (none)
+- **Status:** `extracted`
+
+## agentskills-quickstart
+
+- **URL:** https://agentskills.io/skill-creation/quickstart.md
+- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
+- **Description:** Step-by-step first-skill walkthrough — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc.
+- **Contributing files:** (none)
+- **Status:** `extracted`