You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2c3d270
Browse filesBrowse the repository at this point in the historyBrowse files
- Update `./references/`, `./scripts/`, or `./assets/` only when the evidence shows they will reduce future mistakes.
72
72
- When Step 4 extracted deterministic logic into a new `${SKILL_HOME}/scripts/` script, list that script in the Resources table so the executable resource stays discoverable.
73
73
- Avoid adding process logs, changelogs, or full retrospectives to the Skill; distill only reusable lessons.
74
+
-**Never narrate the document's own history**: corrections state the current fact only — never `旧文档断言…已证伪` / `重要勘误` / `本条不再是限制` frames (exceptions: confidence markers, misuse guards). Rewrite examples: [`./references/skill-slimming-principles.md`](./references/skill-slimming-principles.md)`## No History Narration`.
74
75
-**Rename/removal downstream-wiring checklist**: a rename/consolidation/removal is not done until every downstream pointer moves with it (obsolete-skills list, contract tests, skills-count list, feature history, dogfooded artifacts), and both mirrors are synced and verified byte-equal. Five-step checklist and the move-then-edit ordering rule: [`./references/loop-playbook.md`](./references/loop-playbook.md)`## Step 5`.
75
76
76
77
6.**Validate the improvement loop**
@@ -171,9 +172,10 @@ Objective conditions for finishing a loop. Each is checkable, not a matter of ju
171
172
2.**New detail lands in L2/L3 by default.** Do not add worked examples, full command sequences, or multi-line snippets to `SKILL.md` — write them into `./references/` or `./scripts/` and leave a one-line pointer with an anchor in the body.
172
173
3.**Evidence before defect.** Do not label anything a defect without an observed symptom (error text, wrong output, user correction, artifact). `Unobserved` findings are recorded only; counting signals alone never becomes an optimization point.
173
174
4.**Capability verified before it is documented.** Before writing a delegation path, data table, or coverage claim, read the delegate's real surface (`--help`, contract, cached facts) and encode honest limitation branches. Do not write values or capabilities from memory.
174
-
5.**Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred.
175
+
5.**Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred. For detection scripts also run a **reverse case on a domain-legitimate sample** (must NOT flag required syntax) — catching bad samples alone can induce deleting required syntax.
175
176
6.**Removal preserves content.** Every slimming move is delete-and-absorb in the same edit; never delete a section and defer relocating its substance.
176
177
7.**No claim of "fixed" without before/after.** Improvement outcomes are decided by the intervention ledger's next-run comparison, not by asserting the edit works.
178
+
8.**Wrap-up commits verify the staging area.** Before any loop-end commit, `git status --short` and confirm only this loop's files are staged; unstage unrelated pre-staged entries or commit by explicit pathspec — never `git add -A`.
Copy file name to clipboardExpand all lines: .specify/skills/improve-skills/references/skill-slimming-principles.md
+15Lines changed: 15 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -207,3 +207,18 @@ A slim `SKILL.md` makes the agent's behavior **predictable and auditable**:
207
207
Slimming also has a **measured compliance payoff**. Skill loading is progressive across four levels: **L0** frontmatter `description` (always in context), **L1**`SKILL.md` body (loaded on trigger; keep ≤ ~5K tokens), **L2**`references/` (read on demand), **L3**`scripts/` (executed, near-zero token cost). Hard constraints buried mid-way through a bloated L1 body sit in the attention low-zone and get violated at a measurably higher rate (~72–80% vs ~100% when kept compact and well-placed — see [constraint-placement.md](./constraint-placement.md)). Every manual paragraph left in L1 dilutes the rules that must survive there; moving it to L2/L3 is compliance protection, not just tidiness.
208
208
209
209
Slimming is not a one-time refactor; it is a steady-state discipline applied every time the Skill changes.
210
+
211
+
## No History Narration
212
+
213
+
A Skill document states current facts for the next executor. Corrections replace the
214
+
wrong claim outright; they do not report the replacement.
- Update `./references/`, `./scripts/`, or `./assets/` only when the evidence shows they will reduce future mistakes.
72
72
- When Step 4 extracted deterministic logic into a new `${SKILL_HOME}/scripts/` script, list that script in the Resources table so the executable resource stays discoverable.
73
73
- Avoid adding process logs, changelogs, or full retrospectives to the Skill; distill only reusable lessons.
74
+
-**Never narrate the document's own history**: corrections state the current fact only — never `旧文档断言…已证伪` / `重要勘误` / `本条不再是限制` frames (exceptions: confidence markers, misuse guards). Rewrite examples: [`./references/skill-slimming-principles.md`](./references/skill-slimming-principles.md)`## No History Narration`.
74
75
-**Rename/removal downstream-wiring checklist**: a rename/consolidation/removal is not done until every downstream pointer moves with it (obsolete-skills list, contract tests, skills-count list, feature history, dogfooded artifacts), and both mirrors are synced and verified byte-equal. Five-step checklist and the move-then-edit ordering rule: [`./references/loop-playbook.md`](./references/loop-playbook.md)`## Step 5`.
75
76
76
77
6.**Validate the improvement loop**
@@ -171,9 +172,10 @@ Objective conditions for finishing a loop. Each is checkable, not a matter of ju
171
172
2.**New detail lands in L2/L3 by default.** Do not add worked examples, full command sequences, or multi-line snippets to `SKILL.md` — write them into `./references/` or `./scripts/` and leave a one-line pointer with an anchor in the body.
172
173
3.**Evidence before defect.** Do not label anything a defect without an observed symptom (error text, wrong output, user correction, artifact). `Unobserved` findings are recorded only; counting signals alone never becomes an optimization point.
173
174
4.**Capability verified before it is documented.** Before writing a delegation path, data table, or coverage claim, read the delegate's real surface (`--help`, contract, cached facts) and encode honest limitation branches. Do not write values or capabilities from memory.
174
-
5.**Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred.
175
+
5.**Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred. For detection scripts also run a **reverse case on a domain-legitimate sample** (must NOT flag required syntax) — catching bad samples alone can induce deleting required syntax.
175
176
6.**Removal preserves content.** Every slimming move is delete-and-absorb in the same edit; never delete a section and defer relocating its substance.
176
177
7.**No claim of "fixed" without before/after.** Improvement outcomes are decided by the intervention ledger's next-run comparison, not by asserting the edit works.
178
+
8.**Wrap-up commits verify the staging area.** Before any loop-end commit, `git status --short` and confirm only this loop's files are staged; unstage unrelated pre-staged entries or commit by explicit pathspec — never `git add -A`.
Copy file name to clipboardExpand all lines: skills/improve-skills/references/skill-slimming-principles.md
+15Lines changed: 15 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -207,3 +207,18 @@ A slim `SKILL.md` makes the agent's behavior **predictable and auditable**:
207
207
Slimming also has a **measured compliance payoff**. Skill loading is progressive across four levels: **L0** frontmatter `description` (always in context), **L1**`SKILL.md` body (loaded on trigger; keep ≤ ~5K tokens), **L2**`references/` (read on demand), **L3**`scripts/` (executed, near-zero token cost). Hard constraints buried mid-way through a bloated L1 body sit in the attention low-zone and get violated at a measurably higher rate (~72–80% vs ~100% when kept compact and well-placed — see [constraint-placement.md](./constraint-placement.md)). Every manual paragraph left in L1 dilutes the rules that must survive there; moving it to L2/L3 is compliance protection, not just tidiness.
208
208
209
209
Slimming is not a one-time refactor; it is a steady-state discipline applied every time the Skill changes.
210
+
211
+
## No History Narration
212
+
213
+
A Skill document states current facts for the next executor. Corrections replace the
214
+
wrong claim outright; they do not report the replacement.
0 commit comments