Defame1297
311e7cd22c
Six defects, each one a place where two files that an author reads in the same sitting told them different things — or where the trim dropped a rule and nothing noticed because no gate covers prose. **"Use proactively" contradicted itself across the pair.** All three agent templates said to add it where the runtime should delegate unprompted, while `agent-audit`'s `KyberforgeCopilot.ProactivePhrase` rule grades it a hard FAIL in any `*.agent.md` — which is the Copilot half of every project/user pair *and* the vendor-neutral plugin-scope file, since that compiles to a real Copilot agent downstream. Following the template produced a file the repo's own gate rejects. The phrase is now permitted in exactly one place, the Claude Code `.md`, and `references/contract.md` carries the per-file table plus the consequence authors ask about next: a pair whose CC half has it and whose Copilot half does not is correct, because `agent-audit` checks that both halves describe the same job, not that they match word for word. **The output-schema rule contradicted itself inside one file.** `contract.md` said any content only one branch reaches moves to `references/`, and then offered an "Output format template" body pattern with no qualification. Stated once now, so it is not re-litigated: an output schema stays in the body only when every flow produces it and it is roughly 50 words or less. No third option. **Gotchas tiers disagreed with the script.** `validate.sh` emits the entry count through `suggest()` and exits 0, while `skill-author` and `skill-audit` both called more than five entries a FAIL. Whether a given gotcha earns its place is judgment, so the prose moves to the script's tier rather than the reverse. The paraphrase rule stays a FAIL and is explicitly marked as the auditor's call — no script detects it. **The dispatch exemplar was cited at the wrong number.** `apm-workflow`'s body is 421 words; 554 is its whole-file count. Both `contract.md` and `body-discipline.md` cited 554 while describing a body budget, so an author calibrating against the exemplar overshot by ~30% — the exact whole-file/body-only conflation those two sections exist to warn against, reproduced inside the warning. **"Error handling" came back as a required body element.** It was one of four and is the one that gets dropped, and dropping it is not neutral: an agent handed malformed input with no instruction invents a recovery, and a subagent's invented recovery is invisible to its caller until the output is wrong. Restored in `agent-audit`'s rubric as a SUGGESTION, in `agent-author`'s contract and both scope checklists as a required element, and as an `## Errors` section in all three templates. **`skill-author` Step 4 gains the one check the audit misses.** An empty body reports `PASS SKILL.md body word count 0` — a word gate cannot tell "concise" from "absent". Step 4 now hand-checks for a non-empty section, and its commit verification is conditioned on actually being inside a git worktree, which a skill under `~/.claude/skills/` is not. Also here: absolute repo paths removed from `skill-author`'s SKILL.md and contract.md in favour of naming the skill (`zoom-out`'s description is quoted inline instead of pointed at), the boundary-target universe documented to match the resolver, a two-hops-from-SKILL.md limit on reference chains, and `new-agent.sh`'s next-steps output naming the description budget and the deliberate absence of an agent body gate. Refs: ADR-0020
4.2 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 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.
With metadata.version present, bump 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 git add and git commit — do not stop at staging. Re-run 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.