chore(kyberforge): remove skill-write and skill-improve (AC6)

Completes issue #5. skill-author now covers both create and improve flows;
skill-write and skill-improve are superseded and removed.

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

docs/adr/0013-skill-author-merge.md

@@ -0,0 +1,16 @@
+# Merge skill-write and skill-improve into skill-author
+
+The kyberforge plugin shipped a factory trio: `skill-write` (create), `skill-improve` (apply signals), `skill-audit` (review). Write and improve both embed authoring quality guidance inline. As standards evolve — agentskills.io spec updates, shared scripts, future governance rules — each change requires updating both skills. Plugin cache isolation makes shared reference files unworkable: `../` paths break when a plugin is copied to its install cache, and the spec explicitly prohibits cross-skill file sharing. We therefore merge `skill-write` and `skill-improve` into a single `skill-author` skill.
+
+## Considered options
+
+**Mirror shared files (rejected)** — duplicate `references/body-discipline.md` and any shared scripts into both skill directories with a mirror comment, relying on convention to keep them in sync. Rejected because it compounds as standards grow: every new governance rule, every spec change, requires updating two files with no enforcement mechanism. The maintenance surface is small today but was judged unacceptable as a permanent pattern.
+
+**Status quo (rejected)** — accept that the two skills embed divergent authoring guidance. Rejected because the divergence is already observable: audit/improve loops oscillate (improve applies criteria slightly different from audit's, producing new findings on re-audit). Adding governance rules to both skills independently would worsen this.
+
+## Consequences
+
+- `skill-write` and `skill-improve` are deleted; invocations of `/skill-write` and `/skill-improve` break — users must switch to `/skill-author`.
+- `skill-audit`'s report footer references `/skill-improve`; that reference is now stale. Update deferred to a follow-on issue.
+- `skill-author` uses auto-detect routing: no existing directory → create flow; existing directory + improvement signals → improve flow; existing directory but no signals → ask.
+- Shared scripts (`scripts/new-skill.sh`), reference files, templates, and tests live in one directory. Future governance rules and spec updates have a single target.

plugins/kyberforge/skills/README.md

@@ -14,5 +14,6 @@ skills/
 
 **Shared** — both Claude Code and GitHub Copilot CLI read `skills/<name>/SKILL.md`.
 
-To add a skill, run `/write-skill` in a Claude Code session. Do not write SKILL.md by hand
+To create or improve a skill, run `/skill-author` in a Claude Code session. To review a skill
-without following the authoring standard — trigger descriptions and self-checks are required.
+without modifying it, run `/skill-audit`. Do not write SKILL.md by hand without following the
+authoring standard — trigger descriptions and body discipline are required.

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

@@ -0,0 +1,50 @@
+# skill-author
+
+Author and refine skills conforming to the [agentskills.io](https://agentskills.io) specification — create new skills from scratch or apply improvement signals to existing ones.
+
+## What it does
+
+Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates.
+
+## Before you start
+
+- Run `/grill-me` to resolve design decisions before creating a new skill
+- 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
+
+```
+/skill-author
+```
+
+## Files
+
+| 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 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 |
+| `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 `scripts/new-skill.sh` |
+| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |
+
+## Spec reference
+
+[agentskills.io specification](https://agentskills.io/specification.md)

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

@@ -0,0 +1,243 @@
+---
+name: skill-author
+description: >
+  Use when the user wants to create a new skill from scratch ("write a skill
+  for X", "build a skill that does Y", "create a SKILL.md for Z"), or improve
+  an existing one ("improve this skill", "fix based on feedback", "apply these
+  audit findings", "update based on grill output"). Also use when the user
+  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. 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:
+  category: factory
+---
+
+## Gotchas
+
+- Patching per symptom is the default failure mode. Three eval failures may all trace to one missing instruction — always identify the root cause before editing.
+- Do not create new scripts unless a signal explicitly calls for it. Writing scripts from scratch requires transcript analysis that is out of scope here; flag the opportunity as a suggestion instead.
+
+## Route
+
+Determine which flow to follow before touching the filesystem:
+
+- **No skill directory at the target path** → follow **Creating a new skill**
+- **Directory exists + at least one improvement signal present** → follow **Improving an existing skill**
+- **Directory exists + no signals present** → ask: "No improvement signals found. Did you mean to create a new skill, or do you have feedback to apply?"
+
+Signals include: grill session output, `/skill-audit` findings (PASS/FAIL punch list), inline user feedback, session context describing what went wrong.
+
+## Creating a new skill
+
+### 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.
+
+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?
+- [ ] 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.
+
+**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:
+
+```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.
+
+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.
+
+#### Frontmatter
+
+**`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..."
+- Focus on user intent, not implementation — describe what the user is trying to achieve, not the skill's internal mechanics
+- 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 (max 500 characters)
+- `metadata` — key-value map; use `author`, `version`, `category`
+- `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.
+
+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):
+````markdown
+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; 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/`. Critical rule: **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.
+
+If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory.
+
+### Step 4 — Add references, assets, and tests (if needed)
+
+**`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.
+
+**`tests/`** — test files for scripts in `scripts/`. Use when scripts are complex
+enough to break silently. Test infrastructure (`.bats`, `*_test.*`) belongs here,
+not in `scripts/`. See `tests/README.md` for setup instructions.
+
+If not needed, delete the placeholder READMEs and their directories.
+
+### Step 5 — Validate and close
+
+Run `/skill-audit` on `<destination-dir>/<skill-name>`.
+
+All FAIL findings must be resolved before the skill is considered done.
+
+## Improving an existing skill
+
+### Step 1 — Verify inputs
+
+Confirm the skill directory path exists and that at least one improvement signal is present in the conversation or a referenced file.
+
+If the skill dir is missing, ask for it. If no signals are present, stop: "This skill applies existing signals to a skill. For a blind review without signals, use `/skill-audit` instead."
+
+Signals can come from anywhere in the conversation or referenced files:
+- Grill session output (most common predecessor in the factory sequence)
+- `/skill-audit` findings (PASS/FAIL/SUGGESTION punch list)
+- 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.
+
+Group signals by **root cause**, not symptom. Ask: "What single gap in the skill causes this cluster of failures?" One root cause → one fix. Do not make a separate edit for each symptom.
+
+```text
+Example:
+- Session context: output format is wrong on every run
+- Audit finding: no output template defined
+- User feedback: "I always have to ask it to format the output"
+→ Root cause: SKILL.md has no output format specification → one fix: add an output template
+```
+
+### Step 3 — Announce planned changes
+
+Before editing, state:
+- Which root causes were identified and what evidence supports each
+- Which files will be changed and what will change in each
+
+Then proceed — edits are reversible via git, no approval checkpoint needed.
+
+### Step 4 — Apply changes
+
+Edit any file in the skill directory that the signals point to: SKILL.md, scripts/, references/, assets/, tests/, README.md.
+
+**Generalize, don't patch.** Find the underlying gap, not the specific example that failed. A fix scoped only to the test cases you've seen will overfit and perform worse on new inputs.
+
+**Keep it lean.** Remove instructions that aren't pulling their weight. For every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused skill consistently outperforms an exhaustive one.
+
+**Explain the why.** Reasoning-based instructions outperform rigid directives. If you find yourself writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the agent can apply judgment in edge cases.
+
+If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md.
+
+**On scripts**: Fix and edit existing scripts freely when signals point to them.
+
+### 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,22 @@ 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
+- **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

@@ -51,7 +51,7 @@ fi
 # Validate templates directory exists
 if [[ ! -d "$TEMPLATES_DIR" ]]; then
   echo "Error: templates directory not found at '$TEMPLATES_DIR'." >&2
-  echo "       Run this script from its original location inside the skill-write skill." >&2
+  echo "       Run this script from its original location inside the skill-author skill." >&2
   exit 1
 fi
 
@@ -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

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

@@ -18,7 +18,7 @@ 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/
+bats plugins/kyberforge/skills/skill-author/tests/
 ```
 
 ## Files

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

@@ -1,25 +0,0 @@
-# skill-improve
-
-Apply evidence-based improvements to an existing skill using signals from the current session.
-
-## What it does
-
-Takes an existing skill directory and one or more improvement signals — grill output, audit findings, eval failures, human feedback, or inline session context — and applies targeted edits to the skill files. Groups signals by root cause before editing to avoid per-symptom patching. Hands off to `/skill-audit` when done.
-
-## Before you start
-
-Have at least one improvement signal ready: a grill session output, `/skill-audit` report, eval results, feedback.json, or inline feedback describing what went wrong. If you have no signals and want a blind review, use `/skill-audit` instead.
-
-## Usage
-
-```
-/skill-improve
-```
-
-Provide the skill directory path and any signal files in the conversation. The skill gathers signals from context — you don't need to paste them in a specific format.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Skill instructions for agents |

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

@@ -1,73 +0,0 @@
----
-name: skill-improve
-description: >
-  Use when the user says "improve this skill", "fix this skill based on
-  feedback", "apply these audit findings", or "update the skill based on this
-  grill output". Also use when the user 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. Applies evidence-based improvements to an existing skill. Do not
-  use when the user wants a read-only review only — use /skill-audit instead.
-  Do not use when no improvement signals are present in the conversation or
-  referenced files.
-allowed-tools: Bash Read Write Edit
-metadata:
-  category: factory
----
-
-## Gotchas
-
-- Patching per symptom is the default failure mode. Three eval failures may all trace to one missing instruction — always identify the root cause before editing.
-- Do not create new scripts unless a signal explicitly calls for it. Writing scripts from scratch requires transcript analysis that is out of scope here; flag the opportunity as a suggestion instead.
-
-## Step 1 — Verify inputs
-
-Confirm the skill directory path exists and that at least one improvement signal is present in the conversation or a referenced file.
-
-If the skill dir is missing, ask for it. If no signals are present, stop: "This skill applies existing signals to a skill. For a blind review without signals, use `/skill-audit` instead."
-
-Signals can come from anywhere in the conversation or referenced files:
-- Grill session output (most common predecessor in the factory sequence)
-- `/skill-audit` findings (PASS/FAIL/SUGGESTION punch list)
-- Human feedback (feedback.json, inline in conversation, PR or issue comments)
-- Session context describing what went wrong
-
-## 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.
-
-Group signals by **root cause**, not symptom. Ask: "What single gap in the skill causes this cluster of failures?" One root cause → one fix. Do not make a separate edit for each symptom.
-
-```text
-Example:
-- Session context: output format is wrong on every run
-- Audit finding: no output template defined
-- User feedback: "I always have to ask it to format the output"
-→ Root cause: SKILL.md has no output format specification → one fix: add an output template
-```
-
-## Step 3 — Announce planned changes
-
-Before editing, state:
-- Which root causes were identified and what evidence supports each
-- Which files will be changed and what will change in each
-
-Then proceed — edits are reversible via git, no approval checkpoint needed.
-
-## Step 4 — Apply changes
-
-Edit any file in the skill directory that the signals point to: SKILL.md, scripts/, references/, assets/, tests/, README.md.
-
-**Generalize, don't patch.** Find the underlying gap, not the specific example that failed. A fix scoped only to the test cases you've seen will overfit and perform worse on new inputs.
-
-**Keep it lean.** Remove instructions that aren't pulling their weight. For every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused skill consistently outperforms an exhaustive one.
-
-**Explain the why.** Reasoning-based instructions outperform rigid directives. If you find yourself writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the agent can apply judgment in edge cases.
-
-If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md.
-
-**On scripts**: Fix and edit existing scripts freely when signals point to them.
-
-## 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-write/README.md

@@ -1,53 +0,0 @@
-# skill-write
-
-Author a new skill conforming to the [agentskills.io](https://agentskills.io) specification.
-
-## What it does
-
-1. Scaffolds a full skill directory from annotated templates
-2. Guides filling in `SKILL.md` and supporting files
-3. Validates the result against the spec
-
-## Before you start
-
-This skill produces its best output when you arrive with rich context:
-
-- Run `/grill-me` to resolve design decisions (scope, triggers, patterns)
-- Collect domain research, examples, and reference docs
-- Know the skill name (kebab-case) and destination path
-
-## Usage
-
-```
-/skill-write
-```
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Skill instructions for agents |
-| `scripts/new-skill.sh` | Copies annotated templates to the destination |
-| `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 |
-| `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 |
-| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |
-
-## Placement
-
-Skills can be installed in two locations:
-
-| Type | Path |
-|------|------|
-| Direct (available immediately) | `~/.agents/skills/<name>/` |
-| Plugin (installed via marketplace) | `plugins/<plugin>/skills/<name>/` |
-
-## Spec reference
-
-[agentskills.io specification](https://agentskills.io/specification.md)

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

@@ -1,161 +0,0 @@
----
-name: skill-write
-description: >
-  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. Authors a new
-  skill following the agentskills.io specification — scaffolds the directory
-  structure from annotated templates, fills in SKILL.md and supporting files, then
-  validates the result. Performs best when preceded by a grill session and domain
-  research. Do not use to update an existing well-formed skill — use /skill-improve
-  instead. Do not use to 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.
-
-**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:
-
-```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.
-
-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.
-
-### 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
-
-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
-
-### 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 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, assets, and tests (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.
-
-**`tests/`** — test files for scripts in `scripts/`. Use when scripts are complex
-enough to break silently. Test infrastructure (`.bats`, `*_test.*`) belongs here,
-not in `scripts/`. See `tests/README.md` for setup instructions.
-
-If not needed, delete the placeholder READMEs and their directories.
-
-## Step 5 — Validate
-
-Run `/skill-audit` on `<destination-dir>/<skill-name>`.
-
-All FAIL findings must be resolved before the skill is considered done.

skills-lock.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "skills": {}
+}