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

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.