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

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
skill-author	Use when creating a new skill, or applying audit findings, grill output, eval results or feedback to an existing one. Not read-only review -> `factory-audit`. Not agents -> `agent-author`. Not hooks, instructions or prompts -> `primitive-author`.	Bash Read Write Edit	version category source_keys 1.0.6 factory agentskills-home agentskills-spec agentskills-best-practices agentskills-optimizing-descriptions agentskills-evaluating-skills agentskills-using-scripts agentskills-quickstart

Gotchas

• The 2,770-word / 500-line spec backstop counts the whole file, frontmatter included — a separate measurement from Step 3's body-only gate. Never unify them.
• Never spawn a subagent to audit or recheck your own work — run /factory-audit inline, in the same context as the edits. Clean-context recheck belongs to /forge's outer loop, and a self-spawned subagent's worktree can be torn down by concurrent cleanup, destroying an uncommitted draft.

Step 1 — Dispatch

Condition	Flow	Reference
No skill directory at the target path	Create	references/create.md
Directory exists, at least one improvement signal present	Improve	references/improve.md
Directory exists, no signals	Stop and ask	—

Signals: grill output, /factory-audit findings, inline feedback, eval results, session context describing what went wrong. With none, ask whether the user meant to create a new skill or has feedback to apply.

Read only the reference matching the resolved flow — each is self-contained. If the target sits inside a git worktree, capture rtk git log --oneline -1 before touching the filesystem; Step 4 needs it.

Step 2 — Invocation axis

Decide before writing any description: model-invoked or hand-invoked?

• Hand-invoked — the user types /name and no agent should route to it. Set disable-model-invocation: true and write one plain human-facing sentence: no trigger list, no boundary clause. Skip Step 3's description rules.
• Model-invoked — the default.

Step 3 — Contract

Before writing or editing a description, or restructuring a body, read references/contract.md — the banned-content list, boundary form, include/exclude rubric and body patterns.

Gates /factory-audit enforces in both flows:

• Description — a trigger clause, at most one capability clause, and a boundary clause shaped Not <thing> -> <skill-name> whose target resolves to a real skill or agent. 250 characters SUGGESTION, 400 FAIL, value only.
• Body — decision procedure only: ordered steps, branches, gates, and which reference to load when. 600 words SUGGESTION, 900 FAIL, body only. At two or more mutually exclusive flows a dispatch table is mandatory and each flow gets its own self-contained references/ file.
• Gotchas — each contradicting a reasonable default. A Gotcha paraphrasing a step below it is a FAIL; over five entries is a SUGGESTION only.

Step 4 — Validate and close

Run /factory-audit on the resolved skill directory; resolve every FAIL before reporting done. It checks name-to-directory match, placeholders, both size budgets, boundary-target resolution and script hygiene — do not hand-check those. Hand-check the one thing it misses: an empty body reports PASS SKILL.md body word count 0 (ADR-0020 target: 600), so confirm at least one non-empty section exists.

Versioning: on create, keep the scaffold's 0.1.0 — do not bump it (ADR-0022); on improve, bump the patch version.

Commit verification. Inside a git worktree: once the audit is clean, run rtk git add and rtk git commit — do not stop at staging. Re-run rtk git log --oneline -1 and confirm the hash changed from Step 1's. A non-empty git diff --stat is not proof: staged-but-uncommitted work is part of no commit and is silently lost if the tree is cleaned up. Report done only once the hash has changed. Outside a worktree (a skill under ~/.claude/skills/, say) nothing is committable — report done on a clean audit, naming that as the reason.