feat(kyberforge): replace write-skill with spec-compliant skill-write and add skill-audit

Rewrote the skill authoring factory skill from scratch against the agentskills.io
specification. Renamed write-skill → skill-write (name now matches directory per spec).

skill-write:
- Full scaffold via new-skill.sh (annotated templates for SKILL.md, README.md,
  scripts/, references/, assets/)
- validate.sh checks all spec constraints deterministically (name format/length,
  description length, placeholder detection, line count, script rules)
- SKILL.md body includes description rules, body discipline, patterns, and scripts
  guidance with "why" rationale throughout
- Templates usable standalone by agents and humans

skill-audit:
- Structural validation (via validate.sh) + seven qualitative dimensions
- Produces PASS/FAIL/SUGGESTION punch list with per-FAIL fix proposals
- Report-only: does not apply fixes

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

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

@@ -0,0 +1,151 @@
+---
+name: skill-write
+description: >
+  Author a new skill following the agentskills.io specification — scaffold the
+  directory structure from annotated templates, fill in SKILL.md and supporting
+  files, then validate the result. Use when the user wants to create a new skill
+  from scratch, says "write a skill for X", "build a skill that does Y", or
+  "create a SKILL.md for Z", or wants to make a workflow repeatable or shareable
+  as a reusable command. Performs best when preceded by a grill session and
+  domain research. Do not use to update an existing well-formed skill, write
+  evals, or author agent definition files.
+allowed-tools: Bash Read Write
+metadata:
+  category: factory
+---
+
+## Prerequisites
+
+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.
+
+**Before touching the filesystem, verify you have:**
+- [ ] A clear purpose — what specific task will this skill handle?
+- [ ] Trigger scenarios — when should an agent activate it, including indirect cases?
+- [ ] Skill name (kebab-case) and destination path
+
+If any are missing, stop and ask the user before proceeding.
+
+## Step 1 — Scaffold
+
+Run the copy script with the skill name and destination directory:
+
+```bash
+bash scripts/new-skill.sh <skill-name> <destination-dir>
+```
+
+Examples:
+```bash
+bash scripts/new-skill.sh my-tool ~/.agents/skills/
+bash scripts/new-skill.sh data-analyzer plugins/myplugin/skills/
+```
+
+This creates `<destination-dir>/<skill-name>/` with annotated templates ready to fill in.
+
+## Step 2 — Fill in SKILL.md
+
+Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeholder.
+
+### Frontmatter
+
+**`name`** — already set by the scaffold script. Must exactly match the directory name.
+
+**`description`** — carries the entire triggering burden. Rules:
+- Imperative: "Use when..." not "This skill..."
+- Specific about capabilities ("parses and validates OpenAPI specs", not "helps with APIs")
+- Include indirect triggers: "even if the user doesn't mention X explicitly"
+- Add "Do not use when..." only if a near-miss skill exists that could steal activations
+- Hard limit: 1024 characters — count before finalizing
+
+**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
+- `metadata` — key-value map; use `author`, `version`, `category`
+- `allowed-tools` — space-separated pre-approved tools; reduces permission prompts
+
+### Body — include only what the agent lacks
+
+Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no."
+
+**Include:**
+- Non-obvious sequences or ordering constraints — the agent may skip or reorder steps without this
+- Domain conventions the agent cannot infer from general knowledge — this is the core value a skill adds
+- One default per decision point, plus one escape hatch — never a menu; menus cause the agent to pause or pick arbitrarily
+- Gotchas — facts that defy reasonable assumptions; the agent will get these wrong every time without them
+
+**Exclude:**
+- Concepts the agent already knows (what JSON is, how HTTP works) — adds tokens without changing behavior
+- Exhaustive option lists — pick a default; the agent doesn't benefit from choosing
+- 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
+
+**Gotchas** — highest value; place near the top:
+```markdown
+## Gotchas
+- <Fact that defies a reasonable assumption>
+- <Non-obvious naming discrepancy or hidden constraint>
+```
+
+**Default with escape hatch** (not a menu):
+```markdown
+Use <X> for <task>. For <edge case>, use <Y> instead.
+```
+
+**Prescriptive sequence** (when order is critical or fragile):
+```markdown
+Run exactly:
+\`\`\`bash
+<command>
+\`\`\`
+Do not modify flags.
+```
+
+**Checklist** (multi-step workflows):
+```markdown
+- [ ] Step 1: ...
+- [ ] Step 2: ...
+```
+
+**Conditional reference** (progressive disclosure — load only when needed):
+```
+If <condition>, read `references/<file>.md`.
+```
+
+### Size budget
+
+Keep `SKILL.md` under 500 lines. When approaching the limit:
+- Move reference material to `references/<topic>.md` and load it conditionally
+- Bundle repeated executable logic into `scripts/` rather than reinventing each run
+
+## Step 3 — Add scripts (if needed)
+
+Place executable scripts in `scripts/`. Rules for agentic scripts:
+
+- **No interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin.
+- **Expose `--help`** — concise usage output; keep it short (it enters the agent's context)
+- **Structured output** — data (JSON, CSV) to stdout; diagnostics and progress to stderr
+- **Idempotent** — "create if not exists"; agents may retry on failure
+- **Meaningful exit codes** — `0` success, non-zero failure; document in `--help`
+- **Dry-run support** — add `--dry-run` for destructive operations
+
+If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory.
+
+## Step 4 — Add references and assets (if needed)
+
+**`references/`** — additional documentation loaded on demand. One topic per file.
+Reference conditionally from SKILL.md: `If <condition>, read references/<file>.md`.
+
+**`assets/`** — static resources: templates, schemas, lookup tables.
+Reference by relative path from SKILL.md.
+
+If not needed, delete the placeholder READMEs and their directories.
+
+## Step 5 — Validate
+
+```bash
+bash scripts/validate.sh <destination-dir>/<skill-name>
+```
+
+All checks must pass before the skill is considered done.