From 62aa89b566ed8fcc8ff33a95ff6037da9a91fd9b Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Wed, 24 Jun 2026 18:04:39 +0000 Subject: [PATCH] docs(adr): add ADR-0013 skill-author merge decision Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_016z2ZFYHQCex8yZAMVMTZzZ --- docs/adr/0013-skill-author-merge.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 docs/adr/0013-skill-author-merge.md diff --git a/docs/adr/0013-skill-author-merge.md b/docs/adr/0013-skill-author-merge.md new file mode 100644 index 0000000..4b1ad23 --- /dev/null +++ b/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.