refactor(kyberforge): make skill-write and skill-audit self-contained with shared resources

- Move validate.sh ownership to skill-audit/scripts/ — it is the canonical
  structural validator; skill-write now delegates Step 5 to /skill-audit
- Add skill-write/references/scripts.md and deployment-modes.md for progressive
  disclosure of package runner patterns and plugin cache isolation rules
- Fix skill-audit Step 1 cross-skill path reference (was repo-absolute, now
  skill-relative); add manual fallback for sandboxed/Bash-denied contexts
- Scope Step 2 "read every file" to exclude binaries and unreferenced files
- Fix new-skill.sh next-steps output to reference /skill-audit instead of
  the removed validate.sh
- Remove stale Dependencies section from skill-audit README; flip dependency
  arrow — skill-write depends on skill-audit, not vice versa

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

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

@@ -4,7 +4,7 @@ Audit a skill directory against the agentskills.io specification. Runs structura
 
 ## What it does
 
-1. Runs `validate.sh` from `skill-write` for structural checks (name format, description length, line count, placeholder detection, script rules)
+1. Runs `scripts/validate.sh` for structural checks (name format, description length, line count, placeholder detection, script rules)
 2. Reads all files in the skill directory
 3. Applies qualitative checks across seven dimensions
 4. Outputs a PASS/FAIL/SUGGESTION punch list with a specific fix proposal for every FAIL
@@ -22,8 +22,5 @@ Provide the path to the skill directory to audit when invoking.
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description length, line count, placeholder detection, script executable bit, and interactive-prompt detection |
 | `README.md` | This file |
-
-## Dependencies
-
-Requires `skill-write` to be installed at `plugins/kyberforge/skills/skill-write/` for the structural validation step. If not present, the agent performs structural checks manually.

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

@@ -16,19 +16,15 @@ metadata:
 
 ## Step 1 — Structural validation
 
-Locate the `validate.sh` script from `skill-write`:
-
 ```bash
-bash plugins/kyberforge/skills/skill-write/scripts/validate.sh <skill-dir>
+bash scripts/validate.sh <skill-dir>
 ```
 
-If `validate.sh` is not found, note it and proceed — perform the checks it would cover manually.
-
-List every FAIL from the structural check in the punch list before continuing.
+List every FAIL from the structural check in the punch list before continuing. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 ## Step 2 — Read all skill files
 
-Read every file in the skill directory: `SKILL.md`, `README.md` (if present), all files in `scripts/`, `references/`, and `assets/`. Do not skip files — internal consistency checks require the full picture.
+Read every file in the skill directory: `SKILL.md`, `README.md` (if present), all files in `scripts/`, `references/`, and `assets/`. Skip binary files and files not directly referenced from `SKILL.md`. Do not skip text files — internal consistency checks require the full picture.
 
 ## Step 3 — Qualitative audit
 
@@ -66,6 +62,7 @@ Check each pattern is appropriate and correctly formed:
 - No non-spec files (e.g. META.md, extra config files)
 - 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
 
 ### Formatting
 

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

@@ -18,31 +18,18 @@ This skill produces its best output when you arrive with rich context:
 
 ## Usage
 
-Invoke via your agent tool with `/skill-write`, or follow the steps in `SKILL.md` manually.
-
-**Agent invocation:**
 ```
 /skill-write
 ```
 
-**Manual (human) workflow:**
-```bash
-# 1. Create the scaffold
-bash scripts/new-skill.sh <skill-name> <destination-dir>
-
-# 2. Fill in the templates at <destination-dir>/<skill-name>/
-
-# 3. Validate
-bash scripts/validate.sh <destination-dir>/<skill-name>
-```
-
 ## Files
 
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
 | `scripts/new-skill.sh` | Copies annotated templates to the destination |
-| `scripts/validate.sh` | Validates a skill directory against the spec |
+| `references/scripts.md` | Package runner table and inline dependency patterns (loaded on demand) |
+| `references/deployment-modes.md` | Plugin vs standalone differences and cache isolation rules (loaded on demand) |
 | `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 |

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

@@ -26,6 +26,8 @@ Share those outputs in this conversation: grill context, research docs, examples
 
 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.
+
 ## Step 1 — Scaffold
 
 Run the copy script with the skill name and destination directory:
@@ -42,6 +44,8 @@ bash scripts/new-skill.sh data-analyzer plugins/myplugin/skills/
 
 This creates `<destination-dir>/<skill-name>/` with annotated templates ready to fill in.
 
+If the destination is inside a plugin directory (path contains a `plugin.json`), read `references/deployment-modes.md` before adding any file references to SKILL.md.
+
 ## Step 2 — Fill in SKILL.md
 
 Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeholder.
@@ -130,6 +134,8 @@ Place executable scripts in `scripts/`. Rules for agentic scripts:
 - **Meaningful exit codes** — `0` success, non-zero failure; document in `--help`
 - **Dry-run support** — add `--dry-run` for destructive operations
 
+If the skill needs scripts with external package dependencies or language-specific tooling (Python, TypeScript, Ruby, Go), read `references/scripts.md` for package runner patterns and inline dependency formats.
+
 If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory.
 
 ## Step 4 — Add references and assets (if needed)
@@ -144,8 +150,6 @@ If not needed, delete the placeholder READMEs and their directories.
 
 ## Step 5 — Validate
 
-```bash
-bash scripts/validate.sh <destination-dir>/<skill-name>
-```
+Run `/skill-audit` on `<destination-dir>/<skill-name>`.
 
-All checks must pass before the skill is considered done.
+All FAIL findings must be resolved before the skill is considered done.

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

@@ -0,0 +1,38 @@
+# 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.
+
+## Cache isolation (plugin mode)
+
+When a plugin is installed, its directory is copied to a cache. Only the plugin's own files are copied. **Any path that leaves the skill directory breaks post-install:**
+
+```
+../other-skill/validate.sh              # breaks
+plugins/kyberforge/skills/other-skill/  # breaks
+../../shared/utils.sh                   # breaks
+```
+
+Fix: duplicate the file into the skill's own `scripts/` or `assets/`. There is no plugin-level `shared/` mechanism — the spec defines no cross-skill sharing, and `../` paths are broken by construction.
+
+## Env vars (plugin mode only)
+
+These variables are injected when the plugin is loaded from an install cache. They are **not available in standalone mode.**
+
+| Variable | Value |
+|----------|-------|
+| `${CLAUDE_PLUGIN_ROOT}` | Absolute path to the plugin's install directory. Changes on update. |
+| `${CLAUDE_PLUGIN_DATA}` | Persistent directory that survives updates. Use for `node_modules`, generated state, caches. |
+
+Use `${CLAUDE_PLUGIN_ROOT}` only in hook commands and `.mcp.json` configs — not in SKILL.md body text, since standalone deployments won't have it.
+
+## Standalone mode
+
+Deployed directly to `~/.agents/skills/<name>/`. No plugin context, no env vars injected. All file references must resolve within the skill directory. Skill invocations (e.g. `/skill-audit`) work if the called skill is also installed.
+
+## Cross-tool portability
+
+`SKILL.md` is portable — the same file works in Claude Code and Copilot CLI. Agent definitions and manifest files (`plugin.json`, `hooks.json`) are tool-specific and must be authored separately per tool.
+
+## Shared assets between skills
+
+If two skills in the same plugin need the same file, duplicate it into each skill's `assets/` or `scripts/`. Add a comment in both copies noting the mirror relationship so they stay in sync when the spec changes.

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

@@ -0,0 +1,68 @@
+# Scripts Reference
+
+## Package runners (no install required)
+
+When an existing package does what you need, use a runner directly in SKILL.md without writing a script file.
+
+| Runner | Language | Notes |
+|--------|----------|-------|
+| `uvx package@version` | Python | Recommended. Aggressive caching via uv. |
+| `pipx run 'package==version'` | Python | Broader OS availability. |
+| `npx package@version` | Node.js | Ships with npm/Node.js. |
+| `bunx package@version` | Node.js | Bun environments only. |
+| `deno run npm:package@version` | TypeScript | Requires permission flags (`--allow-read`, etc.). |
+| `go run golang.org/x/...@version` | Go | Built into Go toolchain. |
+
+Always pin versions. Never use `pip install` or `npm install -g` at runtime — they are not idempotent and pollute the environment.
+
+## Inline dependency patterns
+
+Use these when the script requires packages but should remain a single portable file.
+
+**Python (PEP 723 + uv):**
+```python
+# /// script
+# dependencies = [
+#   "beautifulsoup4>=4.12,<5",
+# ]
+# requires-python = ">=3.12"
+# ///
+from bs4 import BeautifulSoup
+```
+```bash
+uv run scripts/extract.py
+```
+
+**TypeScript (Deno):**
+```typescript
+#!/usr/bin/env -S deno run
+import * as cheerio from "npm:cheerio@1.0.0";
+```
+```bash
+deno run scripts/extract.ts
+```
+
+**TypeScript (Bun):**
+```typescript
+#!/usr/bin/env bun
+import * as cheerio from "cheerio@1.0.0";
+```
+```bash
+bun run scripts/extract.ts
+```
+
+**Ruby (bundler/inline):**
+```ruby
+require 'bundler/inline'
+gemfile do
+  source 'https://rubygems.org'
+  gem 'nokogiri', '~> 1.16'
+end
+```
+```bash
+ruby scripts/extract.rb
+```
+
+## Output size
+
+Many harnesses truncate tool output beyond 10–30K characters. Default to a summary or a reasonable output limit. For scripts that can produce large output: support `--offset N` for pagination, or use `--output FILE` to write to disk and keep stdout clean.

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

@@ -84,4 +84,4 @@ echo "  1. Fill in $TARGET/SKILL.md — replace all FILL IN: placeholders"
 echo "  2. Add scripts to scripts/ if needed (or delete the directory)"
 echo "  3. Add docs to references/ if needed (or delete the directory)"
 echo "  4. Add resources to assets/ if needed (or delete the directory)"
-echo "  5. Validate: bash $(dirname "${BASH_SOURCE[0]}")/validate.sh $TARGET"
+echo "  5. Validate: run /skill-audit on $TARGET"