Defame1297
edcc57c0d6
Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
55 lines
2.6 KiB
Markdown
55 lines
2.6 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 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.
|
|
|
|
The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
|
|
which Step 3 loads on every run.
|