From 1ec3e8a1ea7e0a38b7ea6db463def783f89393d5 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 20 Sep 2026 12:34:42 +0000 Subject: [PATCH] docs(skills): stop routing content at the README this branch deleted MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit skill-author still told authors to move description overflow "to the body or to README.md" while this branch deleted every per-skill README.md, every references/README.md and the README scaffold template. factory-audit's skill-file-structure.md bans non-spec files at the skill root, and the line that used to carve README out of that rule went with them. So skill-author created the file, factory-audit failed it, and nothing read it. 8ce5392 fixed the two scripts and missed the reference prose. The two contract.md files now differ deliberately: a skill's overflow goes to the body or a references/ file, an agent's to the body alone, because an agent is a single file with no references/ directory to disclose to. agent-description-quality.md's "the plugin's README.md" is left alone, plugin READMEs being the ones that survive. Deleting retrofit.md also dropped three instructions baa2f5d did not restore with the cut list, two of which retrofit.md itself recorded as having no validator behind them: re-cite sources.md's Contributing files after content moves, since validate-provenance exits 0 on exactly that drift, and re-check a relocated gate's reachability, since a Gotcha moved into one flow's file is invisible to the others and the word counts improve either way. The third is that boundary clauses are plural — contract.md read as a cap where git-remotes carries four. Also: contract.md named an unqualified scripts/validate.sh that does not exist in skill-author, which skill-file-structure.md calls a hard error; and agent-body-and-delegation.md's simile pointed at a stale README row as the characteristic skill defect, a defect class that can no longer occur, replaced with a SKILL.md naming a references/ file that is not there. skill-author 1.0.4, agent-author 1.0.3, factory-audit 1.0.2. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2 --- .../kyberforge/.apm/skills/agent-author/SKILL.md | 2 +- .../.apm/skills/agent-author/references/contract.md | 3 ++- .../kyberforge/.apm/skills/factory-audit/SKILL.md | 2 +- .../references/agent-body-and-delegation.md | 3 ++- .../references/skill-description-quality.md | 2 +- .../kyberforge/.apm/skills/skill-author/SKILL.md | 2 +- .../.apm/skills/skill-author/references/contract.md | 13 +++++++------ .../.apm/skills/skill-author/references/improve.md | 12 +++++++++++- 8 files changed, 26 insertions(+), 13 deletions(-) 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.