feat(kyberforge): improve skill-author — duality description, source_keys guidance, pre-audit checklists, version bump conventions

- references/sources.md: add YAML frontmatter with source_keys to fix provenance chain break
- SKILL.md description: make create/improve duality explicit ("Handles both the full create flow ... and the improve flow ...")
- SKILL.md Step 2: add inline metadata.source_keys instruction — fill early, not deferred to Step 5
- SKILL.md Step 6 (create) / Step 5 (improve): add pre-audit manual checklists and version bump conventions (minor for create, patch for improve)
- README.md: correct false claim that the skill bumps plugin manifests; it bumps metadata.version only

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9

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

@@ -4,7 +4,7 @@ Author and refine skills conforming to the [agentskills.io](https://agentskills.
 
 ## What it does
 
-Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, if the skill lives inside a plugin directory, bumps the plugin version in both manifests.
+Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's `metadata.version` when present (minor for create, patch for improve).
 
 ## Before you start
 

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

@@ -2,12 +2,14 @@
 name: skill-author
 description: >
   Use when the user wants to create a new skill from scratch ("write a skill
-  for X", "build a skill that does Y", "create a SKILL.md for Z"), or improve
+  for X", "build a skill that does Y", "create a SKILL.md for Z") or improve
   an existing one ("improve this skill", "fix based on feedback", "apply these
-  audit findings", "update based on grill output"). Also use when the user
-  provides inline feedback about a skill's behavior and wants it applied, or
-  when a grill session, eval run, or audit has produced findings the user wants
-  acted on — even if they don't say "improve" explicitly. Do not use for read-only review — use
+  audit findings", "update based on grill output"). Handles both the full
+  create flow (scaffold → fill → validate) and the improve flow (signals →
+  root cause → edit → audit). Also use when the user provides inline feedback
+  about a skill's behavior and wants it applied, or when a grill session, eval
+  run, or audit has produced findings the user wants acted on — even if they
+  don't say "improve" explicitly. Do not use for read-only review — use
   /skill-audit instead. Do not use to author agent definition files.
 allowed-tools: Bash Read Write Edit
 metadata:
@@ -92,9 +94,17 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
 **Optional fields** — uncomment and fill in or remove entirely:
 - `license` — include when distributing the skill externally
 - `compatibility` — include if the skill requires specific tools, runtimes, or network access (max 500 characters)
-- `metadata` — key-value map; use `author`, `version`, `category`
+- `metadata` — key-value map; use `author`, `version`, `category`; add `source_keys` now (see below) if research sources are in context
 - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client)
 
+**`metadata.source_keys`** — if research sources are in context, list the relevant slugs here as you write the body; don't defer this to Step 5. Agents that fill in source_keys late tend to omit it entirely. Example:
+```yaml
+metadata:
+  source_keys:
+    - my-source-slug
+    - another-slug
+```
+
 **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.
@@ -200,10 +210,18 @@ If no research `sources.md` is in context, delete `references/sources.md`.
 
 ### Step 6 — Validate and close
 
+Before running the audit, confirm:
+- [ ] Skill name matches the directory name exactly
+- [ ] `description` field is present and non-empty
+- [ ] Body has at least one non-empty section
+- [ ] No `FILL IN:` placeholders remain in any file
+
 Run `/skill-audit` on `<destination-dir>/<skill-name>`.
 
 All FAIL findings must be resolved before the skill is considered done.
 
+If the skill is versioned (`metadata.version`), set it to the next **minor** version (e.g. `0.2.0` → `0.3.0`). New skills without a prior version start at `0.1.0`.
+
 ## Improving an existing skill
 
 ### Step 1 — Verify inputs
@@ -258,4 +276,11 @@ If a signal points to a script or reference file, edit that file directly rather
 
 ### Step 5 — Validate and close
 
+Before running the audit, confirm:
+- [ ] Skill name still matches the directory name
+- [ ] No `FILL IN:` placeholders were introduced
+- [ ] No previously-passing audit checks were broken by the edits
+
 Run `/skill-audit` on the skill directory. Resolve any FAIL findings before considering the improvement complete.
+
+If the skill is versioned (`metadata.version`), bump the **patch** version (e.g. `0.1.0` → `0.1.1`).

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

@@ -1,3 +1,14 @@
+---
+source_keys:
+  - agentskills-home
+  - agentskills-spec
+  - agentskills-best-practices
+  - agentskills-optimizing-descriptions
+  - agentskills-evaluating-skills
+  - agentskills-using-scripts
+  - agentskills-quickstart
+---
+
 # Sources
 
 <!-- agentskills.io/llms.txt was used for initial source discovery and is not listed below; it contributed no skill file content directly. -->