fix(kyberforge): apply skill-audit findings to skill-author

Body discipline: collapsed 4-bullet script rules to single critical callout
(no interactive prompts); full contract stays in references/scripts.md.
stderr discipline: redirect all confirmation/progress output in new-skill.sh
to stderr per scripts.md contract. Also expands references/scripts.md with
input validation and --help guidance.

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

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

@@ -38,6 +38,7 @@ 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?
@@ -84,74 +85,83 @@ 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
+- `compatibility` — include if the skill requires specific tools, runtimes, or network access (max 500 characters)
 - `metadata` — key-value map; use `author`, `version`, `category`
-- `allowed-tools` — space-separated pre-approved tools; reduces permission prompts
+- `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client)
 
 #### 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.
 
-Follow body discipline: one default per decision point, no menus, gotchas near the top. Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no."
+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
+````markdown
 ## Gotchas
 - <Fact that defies a reasonable assumption>
 - <Non-obvious naming discrepancy or hidden constraint>
-```
+````
 
 **Default with escape hatch** (not a menu):
-```markdown
+````markdown
 Use <X> for <task>. For <edge case>, use <Y> instead.
-```
+````
 
 **Prescriptive sequence** (when order is critical or fragile):
-```markdown
+````markdown
 Run exactly:
-\`\`\`bash
+```bash
 <command>
-\`\`\`
-Do not modify flags.
 ```
+Do not modify flags.
+````
 
 **Checklist** (multi-step workflows):
-```markdown
+````markdown
 - [ ] Step 1: ...
 - [ ] Step 2: ...
-```
+````
 
 **Conditional reference** (progressive disclosure — load only when needed):
-```markdown
+````markdown
 If <condition>, read `references/<file>.md`.
-```
+````
 
 **Output format template** (when the skill produces structured output):
-```markdown
+````markdown
 Output format:
-\`\`\`
-<field>: <value>
-<field>: <value>
-\`\`\`
 ```
+<field>: <value>
+<field>: <value>
+```
+````
 For longer templates, place in `assets/<name>.md` and reference conditionally.
 
 #### Size budget
 
-Keep `SKILL.md` under 500 lines and 5,000 tokens. When approaching the limit:
+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
 - Bundle repeated executable logic into `scripts/` rather than reinventing each run
 
 ### Step 3 — Add scripts (if needed)
 
-Place executable scripts in `scripts/`. Two critical rules:
+Place executable scripts in `scripts/`. Critical rule: **no interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin.
 
-- **No interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin.
+Read `references/scripts.md` before writing any script — it covers the full contract: structured output, pinned versions, self-contained deps, idempotency, exit codes, dry-run, error messages, and output size limits.
-- **Expose `--help`** — concise usage output; keep it short (it enters the agent's context)
-
-For the full script contract (self-contained deps, structured output, idempotency, exit codes, dry-run, error messages, output size), read `references/scripts.md`.
 
 If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory.
 
@@ -190,6 +200,8 @@ Signals can come from anywhere in the conversation or referenced files:
 - Human feedback (feedback.json, inline in conversation, PR or issue comments)
 - Session context describing what went wrong
 
+Also verify the `name` field in frontmatter matches the skill's directory name exactly.
+
 ### Step 2 — Gather and group signals
 
 Read the current skill files (SKILL.md and any files in scripts/, references/, assets/, tests/). Then collect all signals from the conversation and any file paths the user has referenced.

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

@@ -70,10 +70,15 @@ Rules for all agentic scripts:
 - **Self-contained** — bundle dependencies inline so the agent can run the script with a single command; do not require a separate install step
 - **Structured output** — data (JSON, CSV) to stdout; diagnostics and progress to stderr
 - **Idempotent** — "create if not exists"; agents may retry on failure
+- **Input constraints** — validate inputs early; reject unknown or ambiguous values with a clear error rather than proceeding silently
 - **Meaningful exit codes** — `0` success, non-zero failure; document in `--help`
 - **Dry-run support** — add `--dry-run` for destructive operations; pair with `--confirm`/`--force` for operations that can't be undone
 - **Error messages** — on failure, state what went wrong, what was expected, and what to try; vague errors leave agents unable to self-correct
 
+## --help output
+
+Keep `--help` output concise — it enters the agent's context window. Include: usage line, one-line description, options with defaults, exit codes. Omit prose explanations.
+
 ## 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-author/scripts/new-skill.sh

@@ -78,12 +78,12 @@ sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/SKILL.md"
 sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/README.md"
 sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/tests/README.md"
 
-echo "Scaffold created: $TARGET"
+echo "Scaffold created: $TARGET" >&2
-echo ""
+echo "" >&2
-echo "Next steps:"
+echo "Next steps:" >&2
-echo "  1. Fill in $TARGET/SKILL.md — replace all FILL IN: placeholders"
+echo "  1. Fill in $TARGET/SKILL.md — replace all FILL IN: placeholders" >&2
-echo "  2. Add scripts to scripts/ if needed (or delete the directory)"
+echo "  2. Add scripts to scripts/ if needed (or delete the directory)" >&2
-echo "  3. Add docs to references/ if needed (or delete the directory)"
+echo "  3. Add docs to references/ if needed (or delete the directory)" >&2
-echo "  4. Add resources to assets/ if needed (or delete the directory)"
+echo "  4. Add resources to assets/ if needed (or delete the directory)" >&2
-echo "  5. Add tests to tests/ if the skill has scripts (or delete the directory)"
+echo "  5. Add tests to tests/ if the skill has scripts (or delete the directory)" >&2
-echo "  6. Validate: run /skill-audit on $TARGET"
+echo "  6. Validate: run /skill-audit on $TARGET" >&2