Defame1297
ede3f06689
Diffing each retrofitted SKILL.md against its replacement references/ files found rules that existed on main and now existed nowhere — relocated in intent, deleted in fact. A trim that loses a rule is not progressive disclosure, it is data loss with a smaller word count. Three had no survivor. The least-privilege guidance for `tools` kept its mechanics and lost the "restrict to what the agent needs" half, so the remaining text read as encouragement to omit the field. The improve flow lost its regression check, so nothing compared the closing audit against the pre-edit state and a PASS quietly becoming a SUGGESTION went unnoticed — restored on both halves of the author pair, since agent-author had dropped its equivalent too. And agent bodies lost "would the agent get this wrong without it?", which mattered more than it looks: ADR-0020 deliberately sets no body word gate for agents, three of the four already sit between 933 and 1,199 words, and the delegation check only fires on procedure a skill already owns. That heuristic was the only brake left. Two more were reachable only from the wrong scope. agent-author tells the reader to load only the file for the resolved scope, but the mcp__ glob syntax for disallowedTools and the five tools no subagent ever receives had both landed in project-user-scope.md. disallowedTools is the ONLY permitted fence at plugin/APM scope, so the scope that needs the syntax most could not reach it, and a plugin-scope run could write a body telling the agent to ask the user a question. Two documents were actively wrong rather than merely thin. agent-audit told auditors that validate.sh resolves boundary targets for skills only; it runs at both scopes, so the auditor was hand-resolving what the script had already decided and could contradict it. And skill-audit routed to its script-troubleshooting reference whenever validate.sh "fails" — but it exits 1 on ordinary content FAILs, the normal outcome for the whole #99 population, so 1,302 words loaded on nearly every audit. A context-budget regression inside the skill that enforces the context budget. Finally, two illustrations taught the shape the gate ERRORs on, unfenced, while an adjacent rubric called it a hard ERROR. LESSONS.md records the reference-chain depth rule flipping from "one level deep" to "two hops, never three". ADR-0020 is silent on it and the reversal rode entirely on the diff; the looser rule is what mandatory dispatch requires. Refs: #99 ADR: 0020 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
---
|
|
source_keys:
|
|
- agentskills-spec
|
|
- agentskills-best-practices
|
|
---
|
|
|
|
# Patterns Reference
|
|
|
|
Upstream source: agentskills.io — best-practices (instruction patterns), specification.
|
|
|
|
Read this when judging the **patterns** dimension: whether each instruction construct a skill uses
|
|
is the right construct for the job and is correctly formed. Formation, not content — a Gotcha's
|
|
*content* is judged in `references/body-discipline.md`.
|
|
|
|
## The constructs and when each is right
|
|
|
|
| Construct | Right when | Wrong when |
|
|
|---|---|---|
|
|
| Gotchas | An environment fact contradicts a reasonable default | Used as a summary of the steps below |
|
|
| Prescriptive sequence | The operation is fragile and flag order or exact arguments must not change | Several approaches are equally valid |
|
|
| Checklist | A multi-step workflow the agent must complete in order | A single step dressed up as a list |
|
|
| Conditional reference | Detail is needed on one branch only | The reference is needed on every run and is loaded blind |
|
|
| Output template | The agent must emit a specific format a caller consumes | The output is prose nobody parses |
|
|
|
|
## Formation rules
|
|
|
|
**Gotchas** sit near the top of the body, before the steps that would otherwise walk into them.
|
|
Placement late in the body is a SUGGESTION, not a FAIL — the content is still correct, it is just
|
|
read after the mistake.
|
|
|
|
**Prescriptive sequences** that quote a fenced block inside another markdown block must escape the
|
|
inner fence as `` \`\`\` ``. An unescaped inner fence terminates the outer block and the remaining
|
|
instructions render as prose.
|
|
|
|
**Conditional references** state a specific trigger, naming a file that exists in the skill's own
|
|
`references/` directory:
|
|
|
|
```text
|
|
If the API returns a non-200 status, read `references/api-errors.md`.
|
|
```
|
|
|
|
That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer
|
|
in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic
|
|
form — pointing at the directory and hoping — defeats
|
|
progressive disclosure, because the agent either loads everything or loads nothing.
|
|
`Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed
|
|
forms are judgment.
|
|
|
|
**Output templates** belong in the body when the agent must emit them on every run, and in
|
|
`references/` when only one dispatch branch produces that output. A template inlined for a branch
|
|
most invocations never take is body-discipline padding.
|
|
|
|
## Auditing guidance
|
|
|
|
Flag as FAIL if:
|
|
|
|
- A Gotcha entry is a general tip or a reminder rather than a fact that defies a reasonable
|
|
assumption
|
|
- An inner code fence is unescaped inside a markdown block, breaking the render
|
|
- A checklist wraps a single step
|
|
- A conditional reference gives no trigger — `Kyberforge.PaddingPhrase` reports the common form
|
|
- The agent must produce a specific format and no output template is given
|
|
|
|
Flag as SUGGESTION if:
|
|
|
|
- Gotchas are correctly formed but placed late in the body
|
|
- An output template is present but permissive where the consumer needs it exact
|
|
- A conditional reference names a trigger that is real but broader than the branch it guards
|