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
skill-author
Author and refine skills conforming to the agentskills.io specification — create new skills from scratch or apply improvement signals to existing ones.
What it does
Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in SKILL.md and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's metadata.version when present (minor for create, patch for improve).
SKILL.md itself carries only the dispatch table, the invocation-axis decision, the contract gates and the shared close; each flow lives in its own self-contained reference file, per ADR-0020.
The contract it teaches
Authored skills are held to the ADR-0020 context budget. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form Not <thing> -> <skill-name> whose target must resolve to a real skill or agent — 250 characters target, 400 hard ceiling. A body carries the decision procedure only — 600 words target, 900 hard ceiling, counting the body alone, which is a separate measurement from the 2,770-word / 500-line whole-file spec backstop. Skills with two or more mutually exclusive flows must dispatch. references/contract.md holds the full rules; assets/templates/SKILL.md encodes them as a fill-in skeleton.
Before a description is written, the skill asks whether the target is model-invoked or hand-invoked. A hand-invoked skill sets disable-model-invocation: true and carries one plain human-facing sentence with no trigger list.
Before you start
- Run
/grill-meto resolve design decisions before creating a new skill - Collect domain research, examples, and constraints
- Know the skill name (kebab-case) and destination path
Placement
scripts/new-skill.sh resolves the mode automatically by walking up from the given path — see references/create.md Step 1 for the full algorithm.
| Mode | Path | Chosen when |
|---|---|---|
| Standalone | <path>/<name>/ |
No apm.yml with a top-level type: field is found walking up from <path>, before hitting .git or the filesystem root |
| Package (APM) | <package-root>/.apm/skills/<name>/ |
A type-bearing apm.yml is found at or above <path> — <path> just needs to be somewhere inside the package |
If the destination resolves inside an APM package, read references/deployment-modes.md — self-containment rules apply to apm compile output the same way they applied to plugin cache isolation.
Usage
/skill-author
Files
| File | Purpose |
|---|---|
README.md |
Human-readable overview of the skill and its files |
SKILL.md |
Skill instructions for agents |
scripts/new-skill.sh |
Walks up from the given path to resolve package vs standalone mode, then copies annotated templates to the resolved destination |
references/create.md |
The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) |
references/improve.md |
The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) |
references/contract.md |
The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) |
references/retrofit.md |
Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) |
references/deployment-modes.md |
APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) |
references/scripts.md |
Package runners, inline dependency patterns, and full script contract (loaded on demand) |
references/sources.md |
Upstream research sources and which skill files each contributed to |
assets/templates/SKILL.md |
Annotated SKILL.md template — emits an ADR-0020-compliant description and body skeleton |
assets/templates/README.md |
Annotated README template for the new skill |
assets/templates/scripts/README.md |
Placeholder for bundled scripts |
assets/templates/references/README.md |
Placeholder for reference docs |
assets/templates/references/sources.md |
Sources provenance template for new skills |
assets/templates/assets/README.md |
Placeholder for static assets |
assets/templates/tests/README.md |
Placeholder for test files |
tests/new-skill.bats |
(source-only) Bats test suite for scripts/new-skill.sh |
tests/README.md |
(source-only) Setup instructions for bats-support and bats-assert test dependencies |
Rows marked (source-only) exist in the authoring source (.apm/skills/skill-author/) but are
not present in an installed plugin: scripts/sync-plugin-content.sh strips
<category>/<name>/tests when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
assets/templates/tests/README.md row above is not source-only — the exclusion is depth-scoped
to <category>/<name>/tests, so the scaffolding template tree ships intact, which
scripts/new-skill.sh depends on at runtime.