feat(kyberforge): merge skill-write and skill-improve into skill-author #5

Closed
opened 2026-06-24 17:37:02 +00:00 by Claude · 4 comments
Collaborator

Context

Standalone issue — justified by ADR-0013 (docs/adr/0013-skill-author-merge.md).

The kyberforge plugin ships a factory trio: skill-write (create from scratch), skill-improve (apply signals to existing), skill-audit (read-only review). Two problems drive this merge:

  1. Divergent quality bars. Both skills embed authoring guidance inline but with slightly different wording. Audit/improve loops oscillate: improve applies criteria that differ subtly from audit's, producing new findings on re-audit, requiring another improve pass — indefinitely.
  2. No viable shared-file mechanism. Plugin cache isolation breaks ../ paths on install. The spec explicitly prohibits cross-skill file sharing. As the agentskills.io spec evolves and governance rules are added, each change would require updating two skills with no enforcement. The maintenance surface compounds.

The fix: merge into skill-author. One set of authoring standards, one set of scripts, one place for future governance rules.


Acceptance criteria (EARS)

  • AC1 — When invoked with no existing skill directory at the target path, skill-author SHALL follow the create flow: scaffold → fill in SKILL.md → add scripts (if needed) → add references/assets/tests (if needed) → validate with /skill-audit.
  • AC2 — When invoked with an existing skill directory and at least one improvement signal present in the conversation, skill-author SHALL follow the improve flow: verify inputs → gather and group signals by root cause → announce planned changes → apply changes → validate with /skill-audit.
  • AC3 — When invoked with an existing skill directory but no improvement signals present, skill-author SHALL ask the user to clarify intent before proceeding.
  • AC4 — scripts/new-skill.sh SHALL be present in skill-author and produce identical scaffold output to its predecessor in skill-write.
  • AC5 — skill-author SHALL pass /skill-audit with no FAIL findings.
  • AC6 — plugins/kyberforge/skills/skill-write/ and plugins/kyberforge/skills/skill-improve/ SHALL be deleted.
  • AC7 — plugins/kyberforge/skills/README.md SHALL reflect the factory duo (skill-author + skill-audit) with no stale references to skill-write or skill-improve.

Brownfield delta

ADDED    plugins/kyberforge/skills/skill-author/SKILL.md
ADDED    plugins/kyberforge/skills/skill-author/README.md
ADDED    plugins/kyberforge/skills/skill-author/scripts/new-skill.sh        (copied from skill-write)
ADDED    plugins/kyberforge/skills/skill-author/references/deployment-modes.md  (copied from skill-write)
ADDED    plugins/kyberforge/skills/skill-author/references/scripts.md       (copied from skill-write)
ADDED    plugins/kyberforge/skills/skill-author/assets/templates/           (copied from skill-write)
ADDED    plugins/kyberforge/skills/skill-author/tests/new-skill.bats        (copied from skill-write)
ADDED    plugins/kyberforge/skills/skill-author/tests/README.md             (copied from skill-write)
MODIFIED plugins/kyberforge/skills/README.md                                (factory trio → factory duo)
REMOVED  plugins/kyberforge/skills/skill-write/
REMOVED  plugins/kyberforge/skills/skill-improve/

Note: skill-audit is unchanged. Its report footer references /skill-improve — that reference is now stale but is deferred to a follow-on issue.


Design notes

Mode detection (AC1–AC3)

The ## Route section at the top of the body handles detection. Logic:

  • No skill directory at target path → create flow
  • Directory exists + signals present → improve flow
  • Directory exists + no signals → 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, inline user feedback, session context describing failures. No explicit --mode flag needed for human invocation. When refactored to a subagent later, a --mode create|improve override can be added as an escape hatch.

SKILL.md structure

---
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. Performs best when preceded
  by a grill session and domain research. 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
(shared — from skill-improve's Gotchas section, verbatim)

## Route
(detection logic above)

## Creating a new skill
Prerequisites → Step 1 Scaffold → Step 2 Fill in SKILL.md → Step 3 Scripts →
Step 4 References/assets/tests → Step 5 Validate
(content verbatim from skill-write, minus the "Do not use to update..." exclusion
in the description, which disappears since skill-author handles both modes)

## Improving an existing skill
Step 1 Verify inputs → Step 2 Gather and group signals → Step 3 Announce →
Step 4 Apply changes → Step 5 Validate
(content verbatim from skill-improve)

The two sections are self-contained. The ## Route section directs the agent to the right one. No conditional branching inside steps.

Frontmatter note

allowed-tools is the union of both predecessor skills: Bash Read Write Edit.
skill-write had Bash Read Write; skill-improve had Bash Read Write Edit.

scripts/new-skill.sh

Copy verbatim from skill-write/scripts/new-skill.sh. After copying, check for any hardcoded references to skill-write inside the script (path strings, comments, help text) and update them to skill-author.

README.md

Write a fresh README for skill-author. The predecessor READMEs in skill-write and skill-improve can serve as a template for the file table format, but the content should reflect the merged skill's actual files.


Task checklist

  • Read plugins/kyberforge/skills/skill-write/SKILL.md and skill-improve/SKILL.md in full before writing anything
  • Read plugins/kyberforge/skills/skill-write/scripts/new-skill.sh to identify any skill-write-specific strings that need updating
  • Create plugins/kyberforge/skills/skill-author/ via bash plugins/kyberforge/skills/skill-write/scripts/new-skill.sh skill-author plugins/kyberforge/skills/ — this gives the scaffold; then overwrite SKILL.md with the merged content
  • Write skill-author/SKILL.md following the structure in Design Notes above
  • Copy references/deployment-modes.md and references/scripts.md from skill-write/references/ to skill-author/references/
  • Copy assets/templates/ from skill-write/assets/ to skill-author/assets/
  • Copy scripts/new-skill.sh from skill-write/scripts/ to skill-author/scripts/; update any internal skill-write references
  • Copy tests/new-skill.bats and tests/README.md from skill-write/tests/ to skill-author/tests/
  • Write skill-author/README.md with an accurate file table
  • Run /skill-audit on plugins/kyberforge/skills/skill-author/ — resolve all FAILs
  • Update plugins/kyberforge/skills/README.md: factory trio → factory duo
  • Delete plugins/kyberforge/skills/skill-write/
  • Delete plugins/kyberforge/skills/skill-improve/
  • Verify install by checking ~/.claude/skills/ symlinks (if installed) still resolve — skill-author must be present, skill-write and skill-improve must be absent

Session handoff notes

  • The grill session that produced this issue was conducted in the main branch; no branch was created
  • The skill-author name was chosen over skill-forge (kyberforge branding) and skill-craft for clarity in isolation — /skill-author is self-describing without plugin context
  • Subagent/orchestrator mode support (--mode create|improve) is explicitly deferred — add it when the subagent refactor happens, not now
  • The audit/improve oscillation problem (skill-audit's criteria vs. skill-improve's inline criteria) is not fully solved by this issue — it is reduced (write and improve now share one quality bar) but skill-author's embedded criteria may still diverge from skill-audit's references/body-discipline.md and references/description-quality.md over time. A follow-on issue should align them. Deferred by user decision.
## Context Standalone issue — justified by ADR-0013 (`docs/adr/0013-skill-author-merge.md`). The kyberforge plugin ships a factory trio: `skill-write` (create from scratch), `skill-improve` (apply signals to existing), `skill-audit` (read-only review). Two problems drive this merge: 1. **Divergent quality bars.** Both skills embed authoring guidance inline but with slightly different wording. Audit/improve loops oscillate: improve applies criteria that differ subtly from audit's, producing new findings on re-audit, requiring another improve pass — indefinitely. 2. **No viable shared-file mechanism.** Plugin cache isolation breaks `../` paths on install. The spec explicitly prohibits cross-skill file sharing. As the agentskills.io spec evolves and governance rules are added, each change would require updating two skills with no enforcement. The maintenance surface compounds. The fix: merge into `skill-author`. One set of authoring standards, one set of scripts, one place for future governance rules. --- ## Acceptance criteria (EARS) - **AC1** — When invoked with no existing skill directory at the target path, `skill-author` SHALL follow the create flow: scaffold → fill in SKILL.md → add scripts (if needed) → add references/assets/tests (if needed) → validate with `/skill-audit`. - **AC2** — When invoked with an existing skill directory and at least one improvement signal present in the conversation, `skill-author` SHALL follow the improve flow: verify inputs → gather and group signals by root cause → announce planned changes → apply changes → validate with `/skill-audit`. - **AC3** — When invoked with an existing skill directory but no improvement signals present, `skill-author` SHALL ask the user to clarify intent before proceeding. - **AC4** — `scripts/new-skill.sh` SHALL be present in `skill-author` and produce identical scaffold output to its predecessor in `skill-write`. - **AC5** — `skill-author` SHALL pass `/skill-audit` with no FAIL findings. - **AC6** — `plugins/kyberforge/skills/skill-write/` and `plugins/kyberforge/skills/skill-improve/` SHALL be deleted. - **AC7** — `plugins/kyberforge/skills/README.md` SHALL reflect the factory duo (`skill-author` + `skill-audit`) with no stale references to `skill-write` or `skill-improve`. --- ## Brownfield delta ``` ADDED plugins/kyberforge/skills/skill-author/SKILL.md ADDED plugins/kyberforge/skills/skill-author/README.md ADDED plugins/kyberforge/skills/skill-author/scripts/new-skill.sh (copied from skill-write) ADDED plugins/kyberforge/skills/skill-author/references/deployment-modes.md (copied from skill-write) ADDED plugins/kyberforge/skills/skill-author/references/scripts.md (copied from skill-write) ADDED plugins/kyberforge/skills/skill-author/assets/templates/ (copied from skill-write) ADDED plugins/kyberforge/skills/skill-author/tests/new-skill.bats (copied from skill-write) ADDED plugins/kyberforge/skills/skill-author/tests/README.md (copied from skill-write) MODIFIED plugins/kyberforge/skills/README.md (factory trio → factory duo) REMOVED plugins/kyberforge/skills/skill-write/ REMOVED plugins/kyberforge/skills/skill-improve/ ``` Note: `skill-audit` is unchanged. Its report footer references `/skill-improve` — that reference is now stale but is deferred to a follow-on issue. --- ## Design notes ### Mode detection (AC1–AC3) The `## Route` section at the top of the body handles detection. Logic: - No skill directory at target path → create flow - Directory exists + signals present → improve flow - Directory exists + no signals → 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, inline user feedback, session context describing failures. No explicit `--mode` flag needed for human invocation. When refactored to a subagent later, a `--mode create|improve` override can be added as an escape hatch. ### SKILL.md structure ``` --- 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. Performs best when preceded by a grill session and domain research. 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 (shared — from skill-improve's Gotchas section, verbatim) ## Route (detection logic above) ## Creating a new skill Prerequisites → Step 1 Scaffold → Step 2 Fill in SKILL.md → Step 3 Scripts → Step 4 References/assets/tests → Step 5 Validate (content verbatim from skill-write, minus the "Do not use to update..." exclusion in the description, which disappears since skill-author handles both modes) ## Improving an existing skill Step 1 Verify inputs → Step 2 Gather and group signals → Step 3 Announce → Step 4 Apply changes → Step 5 Validate (content verbatim from skill-improve) ``` The two sections are self-contained. The `## Route` section directs the agent to the right one. No conditional branching inside steps. ### Frontmatter note `allowed-tools` is the union of both predecessor skills: `Bash Read Write Edit`. `skill-write` had `Bash Read Write`; `skill-improve` had `Bash Read Write Edit`. ### scripts/new-skill.sh Copy verbatim from `skill-write/scripts/new-skill.sh`. After copying, check for any hardcoded references to `skill-write` inside the script (path strings, comments, help text) and update them to `skill-author`. ### README.md Write a fresh README for `skill-author`. The predecessor READMEs in skill-write and skill-improve can serve as a template for the file table format, but the content should reflect the merged skill's actual files. --- ## Task checklist - [x] Read `plugins/kyberforge/skills/skill-write/SKILL.md` and `skill-improve/SKILL.md` in full before writing anything - [x] Read `plugins/kyberforge/skills/skill-write/scripts/new-skill.sh` to identify any `skill-write`-specific strings that need updating - [x] Create `plugins/kyberforge/skills/skill-author/` via `bash plugins/kyberforge/skills/skill-write/scripts/new-skill.sh skill-author plugins/kyberforge/skills/` — this gives the scaffold; then overwrite SKILL.md with the merged content - [x] Write `skill-author/SKILL.md` following the structure in Design Notes above - [x] Copy `references/deployment-modes.md` and `references/scripts.md` from `skill-write/references/` to `skill-author/references/` - [x] Copy `assets/templates/` from `skill-write/assets/` to `skill-author/assets/` - [x] Copy `scripts/new-skill.sh` from `skill-write/scripts/` to `skill-author/scripts/`; update any internal `skill-write` references - [x] Copy `tests/new-skill.bats` and `tests/README.md` from `skill-write/tests/` to `skill-author/tests/` - [x] Write `skill-author/README.md` with an accurate file table - [x] Run `/skill-audit` on `plugins/kyberforge/skills/skill-author/` — resolve all FAILs - [x] Update `plugins/kyberforge/skills/README.md`: factory trio → factory duo - [x] Delete `plugins/kyberforge/skills/skill-write/` - [x] Delete `plugins/kyberforge/skills/skill-improve/` - [x] Verify install by checking `~/.claude/skills/` symlinks (if installed) still resolve — `skill-author` must be present, `skill-write` and `skill-improve` must be absent --- ## Session handoff notes - The grill session that produced this issue was conducted in the `main` branch; no branch was created - The `skill-author` name was chosen over `skill-forge` (kyberforge branding) and `skill-craft` for clarity in isolation — `/skill-author` is self-describing without plugin context - Subagent/orchestrator mode support (`--mode create|improve`) is explicitly deferred — add it when the subagent refactor happens, not now - The audit/improve oscillation problem (skill-audit's criteria vs. skill-improve's inline criteria) is **not** fully solved by this issue — it is reduced (write and improve now share one quality bar) but skill-author's embedded criteria may still diverge from skill-audit's `references/body-discipline.md` and `references/description-quality.md` over time. A follow-on issue should align them. Deferred by user decision.
Author
Collaborator

Progress update

Completed

  • Read skill-write/SKILL.md and skill-improve/SKILL.md in full
  • Read scripts/new-skill.sh to identify skill-write-specific strings
  • Created plugins/kyberforge/skills/skill-author/ via new-skill.sh scaffold
  • Wrote skill-author/SKILL.md following the structure in Design Notes — Gotchas → Route → Creating a new skill → Improving an existing skill
  • Copied references/deployment-modes.md and references/scripts.md from skill-write/references/
  • Copied assets/templates/ from skill-write/assets/
  • Copied scripts/new-skill.sh; updated internal skill-write reference to skill-author
  • Copied tests/new-skill.bats
  • Wrote skill-author/tests/README.md with correct bats path (skill-author/tests/)
  • Wrote skill-author/README.md with accurate file table
  • Updated plugins/kyberforge/skills/README.md: /write-skill → /skill-author + /skill-audit

Deferred (user decision)

  • Run /skill-audit on plugins/kyberforge/skills/skill-author/ — skipped at user request; run to close AC5
  • Delete plugins/kyberforge/skills/skill-write/ — skipped at user request
  • Delete plugins/kyberforge/skills/skill-improve/ — skipped at user request

Notes

  • skill-author is already live — it appeared in the available skills list immediately after SKILL.md was written
  • allowed-tools is the union of both predecessors: Bash Read Write Edit (AC implied by Design Notes)
  • Scaffold placeholder READMEs in scripts/, references/, and assets/ were removed since all three directories now have actual content
## Progress update ### Completed - [x] Read `skill-write/SKILL.md` and `skill-improve/SKILL.md` in full - [x] Read `scripts/new-skill.sh` to identify `skill-write`-specific strings - [x] Created `plugins/kyberforge/skills/skill-author/` via `new-skill.sh` scaffold - [x] Wrote `skill-author/SKILL.md` following the structure in Design Notes — Gotchas → Route → Creating a new skill → Improving an existing skill - [x] Copied `references/deployment-modes.md` and `references/scripts.md` from `skill-write/references/` - [x] Copied `assets/templates/` from `skill-write/assets/` - [x] Copied `scripts/new-skill.sh`; updated internal `skill-write` reference to `skill-author` - [x] Copied `tests/new-skill.bats` - [x] Wrote `skill-author/tests/README.md` with correct bats path (`skill-author/tests/`) - [x] Wrote `skill-author/README.md` with accurate file table - [x] Updated `plugins/kyberforge/skills/README.md`: `/write-skill` → `/skill-author` + `/skill-audit` ### Deferred (user decision) - [ ] Run `/skill-audit` on `plugins/kyberforge/skills/skill-author/` — skipped at user request; run to close AC5 - [ ] Delete `plugins/kyberforge/skills/skill-write/` — skipped at user request - [ ] Delete `plugins/kyberforge/skills/skill-improve/` — skipped at user request ### Notes - `skill-author` is already live — it appeared in the available skills list immediately after SKILL.md was written - `allowed-tools` is the union of both predecessors: `Bash Read Write Edit` (AC implied by Design Notes) - Scaffold placeholder READMEs in `scripts/`, `references/`, and `assets/` were removed since all three directories now have actual content
Author
Collaborator

Progress update

Newly completed since last update

  • Run /skill-audit on plugins/kyberforge/skills/skill-author/ — PASS, no findings (AC5 ✅)
  • Applied 3 additional improvements surfaced by spec validation subagents:
    • Description guidance: added "focus on user intent, not implementation" bullet
    • Scripts guidance: added Self-contained as explicit rule in Step 3
    • Size budget: now reads "under 500 lines and 5,000 tokens"
  • Applied 2 formatting suggestions from skill-audit (code fence tag, Step 5 heading alignment)
  • Committed: a193ccc — feat(kyberforge): add skill-author, merging skill-write and skill-improve

Still deferred

  • Delete plugins/kyberforge/skills/skill-write/ (AC6)
  • Delete plugins/kyberforge/skills/skill-improve/ (AC6)
## Progress update ### Newly completed since last update - [x] Run `/skill-audit` on `plugins/kyberforge/skills/skill-author/` — **PASS, no findings** (AC5 ✅) - [x] Applied 3 additional improvements surfaced by spec validation subagents: - Description guidance: added "focus on user intent, not implementation" bullet - Scripts guidance: added `Self-contained` as explicit rule in Step 3 - Size budget: now reads "under 500 lines and 5,000 tokens" - [x] Applied 2 formatting suggestions from skill-audit (code fence tag, Step 5 heading alignment) - [x] Committed: `a193ccc` — `feat(kyberforge): add skill-author, merging skill-write and skill-improve` ### Still deferred - [ ] Delete `plugins/kyberforge/skills/skill-write/` (AC6) - [ ] Delete `plugins/kyberforge/skills/skill-improve/` (AC6)
Author
Collaborator

Progress update

Completed since last update

  • Validated skill-author against skill-write, skill-improve, and agentskills.io spec docs using 3 parallel subagents
  • Applied all non-eval findings via iterative improve/audit loop:
    • Added name field format constraints (1–64 chars, lowercase+numbers+hyphens, no leading/trailing/consecutive hyphens)
    • Added output format template pattern to ## Patterns
    • Added skill scoping design note before prerequisites checklist
    • Added reference depth rule ("keep chains one level deep")
    • Restored Placement table to README.md
    • Trimmed 8-bullet script rules to 2 inline + full contract deferred to references/scripts.md
    • Added Script contract section to references/scripts.md (error messages, dry-run/confirm pairing, output size, idempotency, exit codes)
    • Updated both Step 5 headings to "Validate and close"
    • Removed "Performs best when preceded by grill session" from description (already in body)
    • Condensed Include/Exclude block to a single forwarding sentence
    • Fixed README Files table: added README.md row, updated references/scripts.md description
  • Clean-room /skill-audit (fresh subagent, no prior context) — PASS, no findings (one suggestion: near-miss routing conflict with still-present skill-write and skill-improve — deferred to AC6)
  • Committed: 7ec34dd — fix(kyberforge): improve skill-author based on spec validation and audit

Deferred

  • Eval guidance (evals/evals.json workflow) — deferred by user decision; follow-on issue
  • Delete plugins/kyberforge/skills/skill-write/ (AC6)
  • Delete plugins/kyberforge/skills/skill-improve/ (AC6)

Notes

  • The near-miss routing suggestion from the clean audit (skill-write and skill-improve still match the same triggers) resolves naturally once AC6 is completed — no description change needed
  • Eval guidance intentionally skipped this session
## Progress update ### Completed since last update - [x] Validated skill-author against skill-write, skill-improve, and agentskills.io spec docs using 3 parallel subagents - [x] Applied all non-eval findings via iterative improve/audit loop: - Added `name` field format constraints (1–64 chars, lowercase+numbers+hyphens, no leading/trailing/consecutive hyphens) - Added output format template pattern to `## Patterns` - Added skill scoping design note before prerequisites checklist - Added reference depth rule ("keep chains one level deep") - Restored Placement table to README.md - Trimmed 8-bullet script rules to 2 inline + full contract deferred to `references/scripts.md` - Added Script contract section to `references/scripts.md` (error messages, dry-run/confirm pairing, output size, idempotency, exit codes) - Updated both Step 5 headings to "Validate and close" - Removed "Performs best when preceded by grill session" from description (already in body) - Condensed Include/Exclude block to a single forwarding sentence - Fixed README Files table: added `README.md` row, updated `references/scripts.md` description - [x] Clean-room `/skill-audit` (fresh subagent, no prior context) — **PASS, no findings** (one suggestion: near-miss routing conflict with still-present skill-write and skill-improve — deferred to AC6) - [x] Committed: `7ec34dd` — `fix(kyberforge): improve skill-author based on spec validation and audit` ### Deferred - [ ] Eval guidance (evals/evals.json workflow) — deferred by user decision; follow-on issue - [ ] Delete `plugins/kyberforge/skills/skill-write/` (AC6) - [ ] Delete `plugins/kyberforge/skills/skill-improve/` (AC6) ### Notes - The near-miss routing suggestion from the clean audit (skill-write and skill-improve still match the same triggers) resolves naturally once AC6 is completed — no description change needed - Eval guidance intentionally skipped this session
Author
Collaborator

AC6 complete. skill-write/ and skill-improve/ deleted in 8b26245.

Also applied two skill-audit findings to skill-author in 252741a:

  • Body discipline: collapsed 4-bullet script rules to single critical callout; full contract stays in references/scripts.md
  • stderr discipline: all confirmation/progress output in new-skill.sh redirected to stderr per scripts.md contract

All 147 CI tests pass.

AC6 complete. `skill-write/` and `skill-improve/` deleted in `8b26245`. Also applied two skill-audit findings to `skill-author` in `252741a`: - Body discipline: collapsed 4-bullet script rules to single critical callout; full contract stays in `references/scripts.md` - stderr discipline: all confirmation/progress output in `new-skill.sh` redirected to stderr per scripts.md contract All 147 CI tests pass.
Defame1297 added this to the Kyberforge basics milestone 2026-06-25 20:06:28 +00:00
Sign in to join this conversation.