diff --git a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md index b4898d5..826a38c 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md +++ b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md @@ -6,7 +6,7 @@ description: > Not read-only review -> `factory-audit`. Not skills -> `skill-author`. allowed-tools: Bash Read Write Edit metadata: - version: "1.0.2" + version: "1.0.3" category: factory source_keys: - context7-websites-code-claude diff --git a/plugins/kyberforge/.apm/skills/agent-author/references/contract.md b/plugins/kyberforge/.apm/skills/agent-author/references/contract.md index ac9c93e..73b90a4 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/agent-author/references/contract.md @@ -29,7 +29,8 @@ A description carries exactly three things: 3. **Boundary clause** — form: `Not -> .` Add one only where a near-miss agent or skill could steal delegations. -Banned from a description; move it to the body or to `README.md`: +Banned from a description; move it to the body — an agent is a single file with no `references/` +directory to move it to: - Capability enumeration or feature lists - Per-scope emission mechanics — which files the author skill writes at which scope changes no diff --git a/plugins/kyberforge/.apm/skills/factory-audit/SKILL.md b/plugins/kyberforge/.apm/skills/factory-audit/SKILL.md index 144cbd7..e9050f8 100644 --- a/plugins/kyberforge/.apm/skills/factory-audit/SKILL.md +++ b/plugins/kyberforge/.apm/skills/factory-audit/SKILL.md @@ -7,7 +7,7 @@ description: > fixes -> agent-author. allowed-tools: Bash Read metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - agentskills-home diff --git a/plugins/kyberforge/.apm/skills/factory-audit/references/agent-body-and-delegation.md b/plugins/kyberforge/.apm/skills/factory-audit/references/agent-body-and-delegation.md index 98077f1..072708f 100644 --- a/plugins/kyberforge/.apm/skills/factory-audit/references/agent-body-and-delegation.md +++ b/plugins/kyberforge/.apm/skills/factory-audit/references/agent-body-and-delegation.md @@ -44,7 +44,8 @@ A plugin-scope agent is a single `.apm/agents/.agent.md` file with no sibl directory. It cannot progressively disclose to itself — it can only delegate to skills. So a procedure spelled out in an agent body that a skill the agent invokes already owns is not a shortcut: it is a second copy of that procedure, and the second copy drifts. This is the -characteristic agent defect, the way a stale README row is the characteristic skill defect. +characteristic agent defect, the way a `SKILL.md` naming a `references/` file that is not there is +the characteristic skill defect. **An agent body that restates a procedure owned by a skill it can invoke is a FAIL.** The Fix is always the same shape: invoke `` instead. diff --git a/plugins/kyberforge/.apm/skills/factory-audit/references/skill-description-quality.md b/plugins/kyberforge/.apm/skills/factory-audit/references/skill-description-quality.md index 6ff1a38..1fca6bc 100644 --- a/plugins/kyberforge/.apm/skills/factory-audit/references/skill-description-quality.md +++ b/plugins/kyberforge/.apm/skills/factory-audit/references/skill-description-quality.md @@ -46,7 +46,7 @@ A model-invoked description carries exactly three things: instead") is only a SUGGESTION unless a second target in the same sentence resolves. Take the script's tier as given and report it once, under Structure. -Everything else belongs in the body or in `README.md`. +Everything else belongs in the body or in a `references/` file. ## Indirect triggers — conditional, never blanket diff --git a/plugins/kyberforge/.apm/skills/skill-author/SKILL.md b/plugins/kyberforge/.apm/skills/skill-author/SKILL.md index cb6fb4c..fc092a5 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/SKILL.md +++ b/plugins/kyberforge/.apm/skills/skill-author/SKILL.md @@ -6,7 +6,7 @@ description: > Not read-only review -> `factory-audit`. Not agent files -> `agent-author`. allowed-tools: Bash Read Write Edit metadata: - version: "1.0.3" + version: "1.0.4" category: factory source_keys: - agentskills-home diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md index f4d03ea..18f526b 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md @@ -7,9 +7,9 @@ source_keys: # The description and body contract -House contract. Every rule here is enforced by `/factory-audit` — -`scripts/validate.sh` for the counts and the boundary targets, the bundled Vale styles for the -prose patterns, and its reference files for the judgment calls. +House contract. Every rule here is enforced by `/factory-audit` — the counts and the boundary +targets by `factory-audit`'s `scripts/validate.sh`, the prose patterns by the Vale styles it +bundles, the judgment calls by its reference files. ## Why the budget exists @@ -28,10 +28,11 @@ A description carries exactly three things: Focus on user intent, not the skill's internal mechanics. 2. **At most one capability clause** — what it does, one clause, no enumeration. Be specific ("parses and validates OpenAPI specs", not "helps with APIs"). -3. **Boundary clause** — form: `Not -> .` Add one only where a near-miss skill - could steal activations. +3. **Boundary clause** — form: `Not -> .` Write one per genuine near-miss + skill that could steal activations: at least one, not exactly one — `git-remotes` carries + four. What is banned is a clause invented for a skill that was never going to compete. -Banned from a description; move it to the body or to `README.md`: +Banned from a description; move it to the body or to a `references/` file: - Capability enumeration or feature lists - Output-format detail ("Produces a compact findings report with Why and Fix per finding") diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/improve.md b/plugins/kyberforge/.apm/skills/skill-author/references/improve.md index c3cb2dc..93e48dc 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/improve.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/improve.md @@ -58,7 +58,7 @@ Then proceed — edits are reversible via git, no approval checkpoint needed. ## Step 4 — Apply changes Edit any file in the skill directory that the signals point to: SKILL.md, `scripts/`, -`references/`, `assets/`, `tests/`, README.md. +`references/`, `assets/`, `tests/`. **Generalize, do not patch.** Find the underlying gap, not the specific example that failed. A fix scoped only to the test cases you have seen will overfit and perform worse on new inputs. @@ -89,6 +89,16 @@ order, stopping once the gate clears; the order puts the cuts that lose the leas Still over after all four means the skill does two jobs: split it rather than compressing prose. +**Re-cite what moved.** After content moves between files, update `references/sources.md`'s +`Contributing files` for every slug whose content moved, and drop any file the edit deleted. +`factory-audit`'s `scripts/validate-provenance.sh` exits 0 on exactly that drift, so a stale +provenance claim ships unless you fix it here. + +**Re-check every relocated gate's reachability.** A Gotcha or gate moved out of the body into one +flow's `references/` file is invisible to every other branch, and the word counts improve either +way. For each one you move, list the flows that need it: it belongs in one flow's file only when +exactly one flow reaches it, otherwise in the body's common-gates section. + If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md.