Defame1297
3811f5481b
Three related half-applied changes from #130, each leaving the corpus in a state its own documentation contradicts. Why: - `assets/templates/SKILL.md` shipped `metadata:` fully commented out, and `new-skill.sh` only substitutes SKILL_NAME. Every scaffolded skill therefore lacked the `metadata.version` ADR-0022 made mandatory and was blocked at first commit by the very hook this PR added. The commented example also read `"1.0"` — neither the `0.1.0` new-skill seed nor valid semver. - `agent-audit/references/scope-project-user.md` still joined `disable-model-invocation` and `user-invocable` with a slash — #125's defect verbatim — while pointing the reader at the file this PR had just corrected to say the opposite. - ADR-0022 required the "when present" bump conditional dropped and `metadata.version` moved into create.md's required list. It was dropped from SKILL.md but left in README.md, and the field was edited in place under a heading that still authorises removing it entirely. Implementation notes: - The template emits `metadata: version: "0.1.0"` live, captioned as required, with the optional keys left commented. `new-skill.bats` gains a case asserting a live key and three-part semver, so this cannot regress. - `description-quality.md` now asserts only what the vendored Copilot research supports: two fields with opposite defaults, and the retired `infer` replaced by the pair rather than by either alone. The unsupported negative it previously stated as fact is gone. - The `1.0.0` retrofit seed is stated in improve.md and retrofit.md, which the retrofit flow actually reads — create.md, where it lived, is unreachable from that path. The compression item moved out of the file-churn checklist, whose preamble excluded the wording-only change it covers. - Executable git commands in these three skills now carry the ADR-0023 rtk prefix. Refs: #125, #127 ADR: 0022, 0023 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
4.3 KiB
name, description, allowed-tools, metadata
| name | description | allowed-tools | metadata | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| skill-author | Use when the user wants to create a new skill from scratch, or apply audit findings, grill output, eval results, or inline feedback to an existing one. Not read-only review -> `skill-audit`. Not agent files -> `agent-author`. | Bash Read Write Edit |
|
Gotchas
- The word gates are two measurements, not two tiers of one rule: the 2,770-word / 500-line spec backstop counts the whole file, Step 3's gate the body alone. Never unify them.
- Never spawn a subagent to audit or recheck your own work — run
/skill-auditinline, 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. - Do not create new scripts unless a signal explicitly calls for it. Writing one from scratch requires out-of-scope transcript analysis — flag the opportunity as a suggestion instead.
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, /skill-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
/nameand no agent should route to it. Setdisable-model-invocation: trueand 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 /skill-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 /skill-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.
Bump metadata.version: the minor version on create (new skills start at 0.1.0) and the patch version on improve.
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.