fix(kyberforge): apply audit findings across skill factory trio

- skill-audit: promote internal-working gotcha to ## Gotchas section;
  narrow cross-plugin path check to exclude tests/ (dev-only, repo-level
  deps are expected); require tests/README.md to declare that dependency
- skill-write/skill-improve: reorder descriptions to lead with "Use when..."
  for consistency with skill-audit and the agentskills.io spec trigger pattern
- skill-write: add tests/README.md with self-contained bats setup instructions;
  remove cross-skill reference to skill-audit's tests/README.md

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

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

@@ -16,6 +16,10 @@ metadata:
   category: factory
 ---
 
+## Gotchas
+
+- Do not output PASS/FAIL per check while auditing — gather findings internally and surface them only in the Step 4 report. Narrating each check as you go is the default failure mode here.
+
 ## Step 1 — Structural validation
 
 ```bash
@@ -30,7 +34,7 @@ Read every file in the skill directory: `SKILL.md`, `README.md` (if present), al
 
 ## Step 3 — Qualitative audit
 
-Work through each dimension internally. Do not output PASS/FAIL per check — this is internal working. Collect findings only; report them in Step 4. Cite file and line number for every finding.
+Work through each dimension internally. Collect findings only; report them in Step 4. Cite file and line number for every finding.
 
 ### Description
 
@@ -69,7 +73,8 @@ Check each pattern is appropriate and correctly formed:
 - No non-spec files at the skill root (e.g. META.md, extra config files outside permitted directories)
 - Optional directories contain real content — not just unfilled placeholder READMEs
 - `README.md` present and accurately describes the skill and its files
-- No cross-plugin path references — paths using `../`, `../../`, or absolute repo paths (e.g. `plugins/kyberforge/skills/...`) break when the plugin is installed to a cache; flag any found
+- No cross-plugin path references in SKILL.md, scripts/, references/, or assets/ — paths using `../`, `../../`, or absolute repo paths (e.g. `plugins/kyberforge/skills/...`) break when the plugin is installed to a cache; flag any found
+- `tests/` is exempt from the cross-plugin path check — test files are dev-only and may reference repo-level test infrastructure (e.g. a shared `tests/test_helper/`). This dependency must be declared in `tests/README.md`; flag if tests exist but `tests/README.md` is absent or does not document the dependency
 
 ### Formatting
 

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

@@ -1,15 +1,15 @@
 ---
 name: skill-improve
 description: >
-  Apply evidence-based improvements to an existing skill. Use when the user
+  Use when the user says "improve this skill", "fix this skill based on
-  says "improve this skill", "fix this skill based on feedback", "apply these
+  feedback", "apply these audit findings", or "update the skill based on this
-  audit findings", or "update the skill based on this grill output". Also use
+  grill output". Also use when the user provides inline feedback about a skill's
-  when the user provides inline feedback about a skill's behavior and wants it
+  behavior and wants it applied, or when a grill session, eval run, or audit has
-  applied, or when a grill session, eval run, or audit has produced findings
+  produced findings the user wants acted on — even if they don't say "improve"
-  the user wants acted on — even if they don't say "improve" explicitly. Do
+  explicitly. Applies evidence-based improvements to an existing skill. Do not
-  not use when the user wants a read-only review only — use /skill-audit
+  use when the user wants a read-only review only — use /skill-audit instead.
-  instead. Do not use when no improvement signals are present in the
+  Do not use when no improvement signals are present in the conversation or
-  conversation or referenced files.
+  referenced files.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: factory

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

@@ -36,7 +36,8 @@ This skill produces its best output when you arrive with rich context:
 | `assets/templates/references/README.md` | Placeholder for reference docs |
 | `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 new-skill.sh — requires bats-support and bats-assert in the repo root's `tests/test_helper/` (see skill-audit's `tests/README.md` for setup) |
+| `tests/new-skill.bats` | Bats test suite for new-skill.sh |
+| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |
 
 ## Placement
 

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

@@ -1,14 +1,14 @@
 ---
 name: skill-write
 description: >
-  Author a new skill following the agentskills.io specification — scaffold the
+  Use when the user wants to create a new skill from scratch, says "write a skill
-  directory structure from annotated templates, fill in SKILL.md and supporting
+  for X", "build a skill that does Y", or "create a SKILL.md for Z", or wants to
-  files, then validate the result. Use when the user wants to create a new skill
+  make a workflow repeatable or shareable as a reusable command. Authors a new
-  from scratch, says "write a skill for X", "build a skill that does Y", or
+  skill following the agentskills.io specification — scaffolds the directory
-  "create a SKILL.md for Z", or wants to make a workflow repeatable or shareable
+  structure from annotated templates, fills in SKILL.md and supporting files, then
-  as a reusable command. Performs best when preceded by a grill session and
+  validates the result. Performs best when preceded by a grill session and domain
-  domain research. Do not use to update an existing well-formed skill, write
+  research. Do not use to update an existing well-formed skill, write evals, or
-  evals, or author agent definition files.
+  author agent definition files.
 allowed-tools: Bash Read Write
 metadata:
   category: factory

plugins/kyberforge/skills/skill-write/tests/README.md

@@ -0,0 +1,28 @@
+# tests/
+
+Test files for scripts bundled with this skill.
+
+## Dependencies
+
+Tests require [bats-support](https://github.com/bats-core/bats-support) and
+[bats-assert](https://github.com/bats-core/bats-assert). The test files load
+helpers from the repo root's `tests/test_helper/`.
+
+From the repo root:
+
+```bash
+git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support
+git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
+```
+
+Run all tests for this skill (from the repo root):
+
+```bash
+bats plugins/kyberforge/skills/skill-write/tests/
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `new-skill.bats` | Bats test suite for `scripts/new-skill.sh` |