torben/chemenu
1
1 Fork 0
Code Issues 35 Pull Requests Actions Packages Releases 37 Activity

instructions/CONTRACT.md: die Imperativ-Titel-Regel gilt Instructions, nicht dem H1 eines SKILL.md #71

New Issue
Closed
opened 2026-09-09 09:00:10 +00:00 by torben · 1 comment
torben commented 2026-09-09 09:00:10 +00:00
Owner
Copy link
Copy source

Ergebnis

Die Regel wurde praezisiert, die fuenf Skill-Titel bleiben unveraendert. Umgesetzt in 663b1c0, Version 4.8.0-beta.10.

instructions/CONTRACT.md § "Writing an instruction" traegt jetzt:

  • am Imperativ-Titel-Bullet die Einschraenkung "This binds the flat instructions/<name>.md form only - a skill's H1 is a different case, below";
  • den Unterabschnitt "A skill's H1 is a name, not an imperative" mit der Regel (name-shaped H1, passend zum name:-Frontmatter), der Begruendung und dem Abschlusssatz "That is the whole exception. Everything else in this section binds a SKILL.md exactly as it binds an instruction" - damit ist auch die Gegenfrage beantwortet, was am Skill sonst noch anders waere: nichts.

Befund (unveraendert gueltig)

instructions/CONTRACT.md § "Writing an instruction" verlangte: "Imperative title. It answers 'what does this tell me to do?'". Alle fuenf Skills verletzten das dem Wortlaut nach: # Wiki Ingest, # Wiki Lint, # Wiki Manage, # Wiki Query, # Wiki Status sind Nomenphrasen.

Die Pruefung gegen die Primaerquelle ergab, dass die Regel zu weit griff, nicht dass die fuenf Dateien zu locker waren:

  • Anthropics Skill-Authoring-Doku (https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) normiert ausschliesslich die Frontmatter-Felder name und description. Zur Ueberschrift im Body steht dort nichts.
  • Anthropics eigene Beispiel-Skills auf derselben Seite heissen # PDF Processing, # BigQuery Data Analysis, # DOCX Processing - genau die Nomenphrase, die die Regel verbieten wuerde.
  • Der H1 eines Skills liegt auf keinem Retrieval-Pfad. Was ueber Auffindbarkeit entscheidet, ist description; die wird beim Start in den System-Prompt geladen, der Body erst beim Zugriff.

Der Abschnitt heisst "Writing an instruction" und steht in einem Dokument, das Instruction und Skill sonst sauber trennt ("Two forms, three reference tiers"). Die Regel war fuer instructions/<name>.md geschrieben; dass sie auch auf SKILL.md gelesen wurde, war eine Nebenwirkung der Platzierung.

Zusaetzlicher Beleg, in der Umsetzungssitzung gefunden: der vendorierte commonplace-Korpus traegt in commonplace/kb/instructions/COLLECTION.md:23 dieselbe Imperativ-Titel-Regel - unabhaengig entstanden - und macht im selben Absatz dieselbe Ausnahme: "For promoted skills, the skill name is the title (write/SKILL.md)." Ein zweiter Stack kam ohne Kenntnis dieses Issues zum selben Ergebnis. Der Satz steht jetzt mit im Contract.

Akzeptanzkriterien

  • instructions/CONTRACT.md sagt ausdruecklich, ob die Imperativ-Titel-Regel fuer instructions/<name>/SKILL.md gilt. Aus dem Text allein - ohne Kenntnis dieses Issues - ist die Frage beantwortbar: das Bullet schraenkt sich selbst ein und verweist nach unten, der Unterabschnitt beantwortet sie.
  • Die fuenf H1 in instructions/wiki-*/SKILL.md sind unveraendert. git show --stat 663b1c0 listet nur instructions/CONTRACT.md, instructions/wiki-ingest/SKILL.md (Schritte 1 und 6, aus #79 - der H1 nicht), CHANGES.md, VERSION.
  • Die Begruendung fuer die Ausnahme steht dort, wo die Regel steht, nicht nur in diesem Issue.
  • tools/wikitool instructions verify und tools/wikitool docs verify laufen ohne neue Findings. Dazu pytest: 1076 passed.

Geaendert

instructions/CONTRACT.md § "Writing an instruction" - Bullet 1 und neuer Unterabschnitt "A skill's H1 is a name, not an imperative".

Herkunft

Analyse aus #65 (Fund 3), Sitzung 2026-09-09. #65 stellte die Frage offen ("gilt die Instruction-Titelregel 1:1 fuer den Skill-H1, oder ist der Skill-Titel ein eigener Fall"); die Primaerquelle wurde im Volltext geprueft und die Entscheidung vom Operator bestaetigt. Umgesetzt in derselben Sitzung wie #72 und #79, die auf denselben Abschnitt zeigten.

## Ergebnis Die Regel wurde praezisiert, die fuenf Skill-Titel bleiben unveraendert. Umgesetzt in `663b1c0`, Version `4.8.0-beta.10`. `instructions/CONTRACT.md` § "Writing an instruction" traegt jetzt: - am Imperativ-Titel-Bullet die Einschraenkung "This binds the flat `instructions/<name>.md` form only - a skill's H1 is a different case, below"; - den Unterabschnitt **"A skill's H1 is a name, not an imperative"** mit der Regel (name-shaped H1, passend zum `name:`-Frontmatter), der Begruendung und dem Abschlusssatz "That is the whole exception. Everything else in this section binds a `SKILL.md` exactly as it binds an instruction" - damit ist auch die Gegenfrage beantwortet, was am Skill sonst noch anders waere: nichts. ## Befund (unveraendert gueltig) `instructions/CONTRACT.md` § "Writing an instruction" verlangte: "**Imperative title.** It answers 'what does this tell me to do?'". Alle fuenf Skills verletzten das dem Wortlaut nach: `# Wiki Ingest`, `# Wiki Lint`, `# Wiki Manage`, `# Wiki Query`, `# Wiki Status` sind Nomenphrasen. Die Pruefung gegen die Primaerquelle ergab, dass die Regel zu weit griff, nicht dass die fuenf Dateien zu locker waren: - Anthropics Skill-Authoring-Doku (<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>) normiert ausschliesslich die Frontmatter-Felder `name` und `description`. Zur Ueberschrift im Body steht dort **nichts**. - Anthropics eigene Beispiel-Skills auf derselben Seite heissen `# PDF Processing`, `# BigQuery Data Analysis`, `# DOCX Processing` - genau die Nomenphrase, die die Regel verbieten wuerde. - Der H1 eines Skills liegt auf keinem Retrieval-Pfad. Was ueber Auffindbarkeit entscheidet, ist `description`; die wird beim Start in den System-Prompt geladen, der Body erst beim Zugriff. Der Abschnitt heisst "Writing an **instruction**" und steht in einem Dokument, das Instruction und Skill sonst sauber trennt ("Two forms, three reference tiers"). Die Regel war fuer `instructions/<name>.md` geschrieben; dass sie auch auf `SKILL.md` gelesen wurde, war eine Nebenwirkung der Platzierung. **Zusaetzlicher Beleg, in der Umsetzungssitzung gefunden:** der vendorierte `commonplace`-Korpus traegt in `commonplace/kb/instructions/COLLECTION.md:23` dieselbe Imperativ-Titel-Regel - unabhaengig entstanden - und macht im selben Absatz dieselbe Ausnahme: "For promoted skills, the skill name is the title (`write/SKILL.md`)." Ein zweiter Stack kam ohne Kenntnis dieses Issues zum selben Ergebnis. Der Satz steht jetzt mit im Contract. ## Akzeptanzkriterien - [x] `instructions/CONTRACT.md` sagt ausdruecklich, ob die Imperativ-Titel-Regel fuer `instructions/<name>/SKILL.md` gilt. Aus dem Text allein - ohne Kenntnis dieses Issues - ist die Frage beantwortbar: das Bullet schraenkt sich selbst ein und verweist nach unten, der Unterabschnitt beantwortet sie. - [x] Die fuenf H1 in `instructions/wiki-*/SKILL.md` sind unveraendert. `git show --stat 663b1c0` listet nur `instructions/CONTRACT.md`, `instructions/wiki-ingest/SKILL.md` (Schritte 1 und 6, aus #79 - der H1 nicht), `CHANGES.md`, `VERSION`. - [x] Die Begruendung fuer die Ausnahme steht dort, wo die Regel steht, nicht nur in diesem Issue. - [x] `tools/wikitool instructions verify` und `tools/wikitool docs verify` laufen ohne neue Findings. Dazu `pytest`: 1076 passed. ## Geaendert `instructions/CONTRACT.md` § "Writing an instruction" - Bullet 1 und neuer Unterabschnitt "A skill's H1 is a name, not an imperative". ## Herkunft Analyse aus #65 (Fund 3), Sitzung 2026-09-09. #65 stellte die Frage offen ("gilt die Instruction-Titelregel 1:1 fuer den Skill-H1, oder ist der Skill-Titel ein eigener Fall"); die Primaerquelle wurde im Volltext geprueft und die Entscheidung vom Operator bestaetigt. Umgesetzt in derselben Sitzung wie #72 und #79, die auf denselben Abschnitt zeigten.
torben added the prio/plannedsize/Sarea/processkind/build labels 2026-09-09 09:00:10 +00:00
torben commented 2026-09-09 14:31:18 +00:00
Author
Owner
Copy link
Copy source

Changelog: Body auf Endstand. Entscheidungsabschnitt wurde zu "Ergebnis" mit dem, was tatsaechlich im Contract steht; alle vier Akzeptanzkriterien abgehakt mit Nachweis. Neu im Befund: der unabhaengige Beleg aus commonplace/kb/instructions/COLLECTION.md:23, der dieselbe Ausnahme macht - in der Umsetzungssitzung gefunden, dem Issue vorher unbekannt. Umgesetzt in 663b1c0, 4.8.0-beta.10. Geschlossen.

**Changelog:** Body auf Endstand. Entscheidungsabschnitt wurde zu "Ergebnis" mit dem, was tatsaechlich im Contract steht; alle vier Akzeptanzkriterien abgehakt mit Nachweis. Neu im Befund: der unabhaengige Beleg aus `commonplace/kb/instructions/COLLECTION.md:23`, der dieselbe Ausnahme macht - in der Umsetzungssitzung gefunden, dem Issue vorher unbekannt. Umgesetzt in `663b1c0`, `4.8.0-beta.10`. Geschlossen.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No labels area/process kind/build prio/planned size/S
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#71