chore(skill-audit): backfill sources provenance from agentskillsio research

Records the upstream agentskills.io sources that informed skill-audit,
continuing the research → docs → skill provenance chain.

- New references/sources.md with 7 extracted sources attributed to skill files;
  agentskills-llms-txt demoted to discovery-only comment per skill-author precedent
- source_keys frontmatter added to SKILL.md (5 slugs), references/body-discipline.md
  (agentskills-spec, agentskills-best-practices), and references/description-quality.md
  (agentskills-spec, agentskills-optimizing-descriptions)

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

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

@@ -25,5 +25,6 @@ Provide the path to the skill directory to audit when invoking.
 | `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description length, line count, placeholder detection, script executable bit, and interactive-prompt detection |
 | `references/description-quality.md` | Spec-grounded rubric for description auditing — loaded when a finding is borderline |
 | `references/body-discipline.md` | Spec-grounded rubric for body discipline auditing — loaded when padding vs necessity is unclear |
+| `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to |
 | `tests/validate.bats` | Bats test suite for validate.sh |
 | `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |

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

@@ -14,6 +14,12 @@ description: >
 allowed-tools: Bash Read
 metadata:
   category: factory
+  source_keys:
+    - agentskills-home
+    - agentskills-spec
+    - agentskills-best-practices
+    - agentskills-optimizing-descriptions
+    - agentskills-using-scripts
 ---
 
 ## Gotchas

plugins/kyberforge/skills/skill-audit/references/body-discipline.md

@@ -1,3 +1,9 @@
+---
+source_keys:
+  - agentskills-spec
+  - agentskills-best-practices
+---
+
 # Body Discipline Reference
 
 Source: agentskills.io — skill-authoring

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

@@ -1,3 +1,9 @@
+---
+source_keys:
+  - agentskills-spec
+  - agentskills-optimizing-descriptions
+---
+
 # Description Quality Reference
 
 Source: agentskills.io — optimizing-descriptions

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

@@ -0,0 +1,52 @@
+# Sources
+
+<!-- agentskills.io/llms.txt was used for initial source discovery and is not listed below; it contributed no skill file content directly. -->
+
+## agentskills-home
+
+- **URL:** https://agentskills.io/home.md
+- **Description:** Agent Skills overview — what it is, why it exists, progressive disclosure model, ecosystem of 35+ implementing tools
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-spec
+
+- **URL:** https://agentskills.io/specification.md
+- **Description:** Complete SKILL.md format specification — frontmatter fields, constraints, body content, optional directories, progressive disclosure levels, file references, validation
+- **Contributing files:** SKILL.md, references/body-discipline.md, references/description-quality.md
+- **Status:** `extracted`
+
+## agentskills-best-practices
+
+- **URL:** https://agentskills.io/skill-creation/best-practices.md
+- **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops)
+- **Contributing files:** SKILL.md, references/body-discipline.md
+- **Status:** `extracted`
+
+## agentskills-optimizing-descriptions
+
+- **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md
+- **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop
+- **Contributing files:** SKILL.md, references/description-quality.md
+- **Status:** `extracted`
+
+## agentskills-evaluating-skills
+
+- **URL:** https://agentskills.io/skill-creation/evaluating-skills.md
+- **Description:** Eval-driven skill quality improvement — test case design, workspace structure, assertion writing, grading, benchmarking, human review, iteration loop
+- **Contributing files:** (none — eval workflow not directly informing audit dimensions)
+- **Status:** `extracted`
+
+## agentskills-using-scripts
+
+- **URL:** https://agentskills.io/skill-creation/using-scripts.md
+- **Description:** Using scripts in skills — one-off commands, self-contained scripts with inline dependencies, designing scripts for agentic use (no interactive prompts, --help, structured output, idempotency)
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-quickstart
+
+- **URL:** https://agentskills.io/skill-creation/quickstart.md
+- **Description:** Step-by-step guide to creating a first skill (roll-dice example), how discovery/activation/execution work in practice
+- **Contributing files:** (none — creation guide not directly informing audit criteria)
+- **Status:** `extracted`

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

@@ -36,10 +36,12 @@ If the destination is inside a plugin directory, read `references/deployment-mod
 | `scripts/new-skill.sh` | Copies annotated templates to the destination to scaffold a new skill |
 | `references/deployment-modes.md` | Plugin vs standalone differences and cache isolation rules (loaded on demand) |
 | `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) |
+| `references/sources.md` | Upstream research sources and which skill files each contributed to |
 | `assets/templates/SKILL.md` | Annotated SKILL.md template |
 | `assets/templates/README.md` | Annotated README template for the new skill |
 | `assets/templates/scripts/README.md` | Placeholder for bundled scripts |
 | `assets/templates/references/README.md` | Placeholder for reference docs |
+| `assets/templates/references/sources.md` | Sources provenance template for new skills |
 | `assets/templates/assets/README.md` | Placeholder for static assets |
 | `assets/templates/tests/README.md` | Placeholder for test files |
 | `tests/new-skill.bats` | Bats test suite for `scripts/new-skill.sh` |

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

@@ -13,6 +13,14 @@ description: >
 allowed-tools: Bash Read Write Edit
 metadata:
   category: factory
+  source_keys:
+    - agentskills-home
+    - agentskills-spec
+    - agentskills-best-practices
+    - agentskills-optimizing-descriptions
+    - agentskills-evaluating-skills
+    - agentskills-using-scripts
+    - agentskills-quickstart
 ---
 
 ## Gotchas
@@ -38,7 +46,6 @@ Run `/grill-me` on the skill's design and research the target domain first.
 Share those outputs in this conversation: grill context, research docs, examples, constraints.
 
 Design for one coherent user intent — skills too narrow force multiple loads per task; too broad are hard to activate precisely.
-Extract the skill from a real task you've done — a skill refined from real execution outperforms one written speculatively.
 
 **Before touching the filesystem, verify you have:**
 - [ ] A clear purpose — what specific task will this skill handle?
@@ -47,7 +54,7 @@ Extract the skill from a real task you've done — a skill refined from real exe
 
 If any are missing, stop and ask the user before proceeding.
 
-**Requires `/skill-audit`** — used in Step 5 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/skill-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing.
+**Requires `/skill-audit`** — used in Step 6 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/skill-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing.
 
 ### Step 1 — Scaffold
 
@@ -71,7 +78,7 @@ If the destination is inside a plugin directory (path contains a `plugin.json`),
 
 Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeholder.
 
-#### Frontmatter
+**Frontmatter**
 
 **`name`** — already set by the scaffold script. Must exactly match the directory name. Format: 1–64 characters, lowercase letters/numbers/hyphens only, no leading, trailing, or consecutive hyphens (`--`).
 
@@ -89,7 +96,7 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
 - `metadata` — key-value map; use `author`, `version`, `category`
 - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client)
 
-#### Body — include only what the agent lacks
+**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.
 
@@ -107,7 +114,7 @@ Ask of every sentence: "Would the agent get this wrong without it?" Cut anything
 - Steps the agent handles independently — over-specifying leads agents to follow unproductive paths
 - Restatements of the description — it's already in context; repeating it wastes the token budget
 
-#### Patterns
+**Patterns**
 
 **Gotchas** — highest value; place near the top:
 ````markdown
@@ -151,7 +158,7 @@ Output format:
 ````
 For longer templates, place in `assets/<name>.md` and reference conditionally.
 
-#### Size budget
+**Size budget**
 
 Keep `SKILL.md` under 500 lines; 5,000 tokens is the recommended body budget. When approaching the limit:
 - Move reference material to `references/<topic>.md` and load it conditionally
@@ -180,7 +187,19 @@ not in `scripts/`. See `tests/README.md` for setup instructions.
 
 If not needed, delete the placeholder READMEs and their directories.
 
-### Step 5 — Validate and close
+### Step 5 — Populate or delete `references/sources.md`
+
+If a research `sources.md` is present in the conversation context:
+
+1. Read it and filter to entries with `` `extracted` `` status only.
+2. For each entry, determine which skill files it contributed to (SKILL.md and any files in references/ that drew from it). Update `Contributing files` accordingly — list skill files, not research topic files.
+3. Write the updated content to `references/sources.md`.
+4. Add `source_keys` to the frontmatter of `SKILL.md` (under `metadata`) listing the slugs of sources that informed it.
+5. For each file in `references/` that was informed by research sources, add `source_keys` frontmatter (same format as research topic files) listing the relevant slugs.
+
+If no research `sources.md` is in context, delete `references/sources.md`.
+
+### Step 6 — Validate and close
 
 Run `/skill-audit` on `<destination-dir>/<skill-name>`.
 

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

@@ -31,6 +31,13 @@ description: >
 # Optional. Arbitrary key-value map. Common keys: author, version, category.
 # No restrictions on keys or values.
 
+# source_keys:
+#   - source-slug-one
+#   - source-slug-two
+# Optional. Populated when this skill was built from /research output.
+# Lists slugs from references/sources.md that informed this file.
+# Also add source_keys to each references/*.md file that was informed by research.
+
 # allowed-tools: Bash Read Write
 # Optional (experimental — support varies by client).
 # Space-separated list of pre-approved tools.

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

@@ -0,0 +1,13 @@
+# Sources
+
+<!-- Populated at Step 5 of skill authoring, after all skill files are written.
+     For each research source with status `extracted`, record which skill files
+     it contributed to under Contributing files.
+     Delete this file if no research sources were provided as input. -->
+
+## FILL IN: source-slug
+
+- **URL:** FILL IN
+- **Description:** FILL IN
+- **Contributing files:** FILL IN: list skill files this source informed (e.g. SKILL.md, references/foo.md)
+- **Status:** `extracted`

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

@@ -1,3 +1,8 @@
+---
+source_keys:
+  - agentskills-spec
+---
+
 # Deployment Modes
 
 Skills deploy in two modes. Both resolve relative paths from the skill root — the SKILL.md body works the same in either. Differences only arise when referencing files *outside* the skill directory.

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

@@ -1,3 +1,8 @@
+---
+source_keys:
+  - agentskills-using-scripts
+---
+
 # Scripts Reference
 
 ## Package runners (no install required)

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

@@ -0,0 +1,53 @@
+# Sources
+
+<!-- agentskills.io/llms.txt was used for initial source discovery and is not listed below; it contributed no skill file content directly. -->
+
+## agentskills-home
+
+- **URL:** https://agentskills.io/home.md
+- **Description:** Agent Skills overview — what it is, why it exists, progressive disclosure model, ecosystem of 35+ implementing tools
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-spec
+
+- **URL:** https://agentskills.io/specification.md
+- **Description:** Complete SKILL.md format specification — frontmatter fields, constraints, body content, optional directories, progressive disclosure levels, file references, validation
+- **Contributing files:** SKILL.md, references/deployment-modes.md
+- **Status:** `extracted`
+
+## agentskills-best-practices
+
+- **URL:** https://agentskills.io/skill-creation/best-practices.md
+- **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops)
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-optimizing-descriptions
+
+- **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md
+- **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-evaluating-skills
+
+- **URL:** https://agentskills.io/skill-creation/evaluating-skills.md
+- **Description:** Eval-driven skill quality improvement — test case design, workspace structure, assertion writing, grading, benchmarking, human review, iteration loop
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## agentskills-using-scripts
+
+- **URL:** https://agentskills.io/skill-creation/using-scripts.md
+- **Description:** Using scripts in skills — one-off commands, self-contained scripts with inline dependencies, designing scripts for agentic use (no interactive prompts, --help, structured output, idempotency)
+- **Contributing files:** SKILL.md, references/scripts.md
+- **Status:** `extracted`
+
+## agentskills-quickstart
+
+- **URL:** https://agentskills.io/skill-creation/quickstart.md
+- **Description:** Step-by-step guide to creating a first skill (roll-dice example), how discovery/activation/execution work in practice
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+

plugins/kyberforge/skills/skill-author/scripts/new-skill.sh

@@ -20,8 +20,8 @@ Output:
   Creates <destination-dir>/<skill-name>/ with annotated templates ready to fill in.
 
 Exit codes:
-  0  Scaffold created successfully
+  0  Scaffold created successfully, or destination already exists (no-op)
-  1  Invalid arguments or destination already exists
+  1  Invalid arguments, missing destination parent, or templates not found
 EOF
 }
 
@@ -63,11 +63,10 @@ fi
 
 TARGET="$DEST_DIR/$SKILL_NAME"
 
-# Refuse to overwrite existing directory
+# Destination already exists — treat as a no-op so retries are safe
 if [[ -d "$TARGET" ]]; then
-  echo "Error: '$TARGET' already exists." >&2
+  echo "Scaffold already exists at '$TARGET' — nothing to do." >&2
-  echo "       Remove it first or choose a different name." >&2
+  exit 0
-  exit 1
 fi
 
 # Copy templates to destination

plugins/kyberforge/skills/skill-author/tests/new-skill.bats

@@ -111,8 +111,9 @@ teardown() {
     assert_failure
 }
 
-@test "fails when target already exists" {
+@test "exits 0 when target already exists (no-op)" {
     mkdir -p "$DEST/my-tool"
     run bash "$SCRIPT" my-tool "$DEST"
-    assert_failure
+    assert_success
+    assert_output --partial "nothing to do"
 }