fix(kyberforge): improve skill-author based on spec validation and audit

- Add name field format constraints (1-64 chars, hyphens rules)
- Add output format template pattern to ## Patterns
- Add scope design note before prerequisites checklist
- Add reference depth rule (one level deep)
- Restore Placement table to README
- Trim script rules to 2 inline + full contract in references/scripts.md
- Add script contract section to references/scripts.md (error messages,
  dry-run/confirm pairing, output size, idempotency, exit codes)
- Update Step 5 headings to "Validate and close" in both flows
- Remove "Performs best when preceded by grill session" from description
- Condense Include/Exclude block to single forwarding sentence
- Fix README Files table: add README.md row, update scripts.md description

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

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

@@ -12,6 +12,15 @@ Routes to one of two flows based on context: if no skill directory exists at the
 - Collect domain research, examples, and constraints
 - Know the skill name (kebab-case) and destination path
 
+## Placement
+
+| Type | Path |
+|------|------|
+| Direct (available immediately after install) | `~/.agents/skills/<name>/` |
+| Plugin (installed via marketplace) | `plugins/<plugin>/skills/<name>/` |
+
+If the destination is inside a plugin directory, read `references/deployment-modes.md` — cache isolation rules apply.
+
 ## Usage
 
 ```
@@ -22,10 +31,11 @@ Routes to one of two flows based on context: if no skill directory exists at the
 
 | File | Purpose |
 |------|---------|
+| `README.md` | Human-readable overview of the skill and its files |
 | `SKILL.md` | Skill instructions for agents |
 | `scripts/new-skill.sh` | Copies annotated templates to the destination to scaffold a new skill |
 | `references/deployment-modes.md` | Plugin vs standalone differences and cache isolation rules (loaded on demand) |
-| `references/scripts.md` | Package runner table and inline dependency patterns (loaded on demand) |
+| `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (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-author/SKILL.md

@@ -8,8 +8,7 @@ description: >
   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. Authors and refines
-  skills following the agentskills.io specification. Performs best when preceded
-  by a grill session and domain research. Do not use for read-only review — use
+  skills following the agentskills.io specification. 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:
@@ -38,6 +37,8 @@ Signals include: grill session output, `/skill-audit` findings (PASS/FAIL punch
 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.
+
 **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?
@@ -71,7 +72,7 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
 
 #### Frontmatter
 
-**`name`** — already set by the scaffold script. Must exactly match the directory name.
+**`name`** — already set by the scaffold script. Must exactly match the directory name. Format: 1–64 characters, lowercase letters/numbers/hyphens only, no leading, trailing, or consecutive hyphens (`--`).
 
 **`description`** — carries the entire triggering burden. Rules:
 - Imperative: "Use when..." not "This skill..."
@@ -91,19 +92,7 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
 
 Rename the placeholder section heading to one that fits the skill's structure — `## Step 1`, `## Workflow`, `## Instructions`, etc.
 
-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
+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."
 
 #### Patterns
 
@@ -139,6 +128,16 @@ Do not modify flags.
 If <condition>, read `references/<file>.md`.
 ```
 
+**Output format template** (when the skill produces structured output):
+```markdown
+Output format:
+\`\`\`
+<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:
@@ -147,17 +146,12 @@ Keep `SKILL.md` under 500 lines and 5,000 tokens. When approaching the limit:
 
 ### Step 3 — Add scripts (if needed)
 
-Place executable scripts in `scripts/`. Rules for agentic scripts:
+Place executable scripts in `scripts/`. Two critical rules:
 
-- **Self-contained** — bundle dependencies inline so the agent can run the script with a single command; do not require a separate install step
 - **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 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.
+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.
 
@@ -165,6 +159,7 @@ If no scripts are needed, delete `scripts/README.md` and the `scripts/` director
 
 **`references/`** — additional documentation loaded on demand. One topic per file.
 Reference conditionally from SKILL.md: `If <condition>, read references/<file>.md`.
+Keep reference chains one level deep — a reference file that references another reference file is rarely loaded correctly.
 
 **`assets/`** — static resources: templates, schemas, lookup tables.
 Reference by relative path from SKILL.md.
@@ -175,7 +170,7 @@ not in `scripts/`. See `tests/README.md` for setup instructions.
 
 If not needed, delete the placeholder READMEs and their directories.
 
-### Step 5 — Validate
+### Step 5 — Validate and close
 
 Run `/skill-audit` on `<destination-dir>/<skill-name>`.
 
@@ -231,6 +226,6 @@ If a signal points to a script or reference file, edit that file directly rather
 
 **On scripts**: Fix and edit existing scripts freely when signals point to them.
 
-### Step 5 — Validate
+### Step 5 — Validate and close
 
 Run `/skill-audit` on the skill directory. Resolve any FAIL findings before considering the improvement complete.

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

@@ -63,6 +63,17 @@ end
 ruby scripts/extract.rb
 ```
 
+## Script contract
+
+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
+- **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
+
 ## 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.