Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Defame1297
2026-07-04 16:45:50 +00:00
parent b521083335
commit 7e3cb90359
4 changed files with 181 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
plugins/kyberforge/skills/forge/README.md Normal file
View File

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

62
plugins/kyberforge/skills/forge/SKILL.md Normal file
View File

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

81
plugins/kyberforge/skills/forge/references/sources.md Normal file
View File

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