|
1 | 1 | --- |
2 | | -description: "Skill and agent bodies state the current rule and its reason, never the incident, PR, or model that motivated it, and name their successor in a `## Next` section; read before editing any skill body" |
| 2 | +description: "Skill and agent bodies carry a four-part verification record for any volatile specific they restate, and name their successor in a `## Next` section; read before editing any skill body" |
3 | 3 | paths: |
4 | 4 | - "plugins/*/skills/**" |
5 | 5 | - "plugins/*/agents/**" |
6 | 6 | --- |
7 | 7 |
|
8 | 8 | # Skill bodies state current rules |
9 | 9 |
|
10 | | -A skill body is read by the model on every invocation. Its authority is the behavior it |
11 | | -prescribes, not the incident that motivated it, so the body carries the rule and the reason and |
12 | | -nothing about how the rule got there. This follows the bundled `/claude-api prompt-audit` guide |
13 | | -(Group 2, "Brittle skill files"). |
14 | | - |
15 | | -Keep out of a skill or agent body: |
16 | | - |
17 | | -- Issue and pull-request numbers from this repository, incident IDs, and past-tense narration of |
18 | | - why a rule exists ("this was added after ...", "an earlier version claimed ..."). |
19 | | -- Pinned model names in behavioral guidance. A rule that only holds on one model belongs in the |
20 | | - `playbooks` model-adaptation chapters, not in a skill body. |
21 | | -- Date-conditional guidance ("before 2026-08 ...", "until version X ships ..."). |
22 | | -- Hardcoded paths, flags, and version numbers stated as bare fact with no verification. |
23 | | - |
24 | | -Keep in the body: |
25 | | - |
26 | | -- The rule, stated in the present tense, with the reason beside it. |
27 | | -- A pointer to an external upstream source (an official doc page, an upstream issue) when the rule |
28 | | - restates a volatile specific it cannot defer to at read time, recorded as the four-part |
29 | | - verification record the |
30 | | - [upstream-drift convention](../../docs/conventions/upstream-drift/README.md) defines: claim, |
31 | | - basis, as-of date, recheck trigger. A dated verification with a trigger is the correct form; an |
32 | | - undated claim is the defect. |
33 | | - |
34 | | -History belongs in the plugin's `CHANGELOG.md`, the commit message, and `docs/adr/`. A reader who |
35 | | -needs the archaeology finds it there; the model reading the skill does not need it to act. |
36 | | - |
37 | | -The platform skill-authoring guidance recommends the opposite shape for superseded guidance: an |
38 | | -in-body "Old patterns" section inside a collapsed `<details>` block |
39 | | -([content guidelines](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#content-guidelines), |
40 | | -verified 2026-09-10). This repository deviates on purpose: every body line is a recurring token |
41 | | -cost on invocation, so history routes to the CHANGELOG, the commit, and `docs/adr/`, and a volatile |
42 | | -specific carries the four-part record above instead of a legacy stanza. Recheck this paragraph when |
43 | | -that page drops or changes the "Old patterns" recommendation. |
| 10 | +A pointer to an external upstream source (an official doc page, an upstream issue) is required |
| 11 | +when a skill or agent body restates a volatile specific it cannot defer to at read time, recorded |
| 12 | +as the four-part verification record the |
| 13 | +[upstream-drift convention](../../docs/conventions/upstream-drift/README.md) defines: claim, |
| 14 | +basis, as-of date, recheck trigger. A dated verification with a trigger is the correct form; an |
| 15 | +undated claim is the defect. |
44 | 16 |
|
45 | 17 | ## Successor sections |
46 | 18 |
|
|
0 commit comments