instructions: the agent speaks the KB language in chat - AGENTS.md § Conversation language, and instructions sync compiles the language tag into every published SKILL.md (#116); 10.0.0-beta.9
CI / verify (push) Successful in 8m6s
CI / pwsh (push) Successful in 2m50s
Release / release (push) Successful in 33s
Release / wiki-mirror (push) Skipped

Files changed:
- AGENTS.md
- CHANGES.md
- VERSION
- docs/explanation/language-boundaries.md
- docs/reference/commands/types-instructions-and-docs.md
- instructions/CONTRACT.md
- instructions/dev/stack-build/SKILL.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- kb/CONVENTIONS.md
- kb/CONVENTIONS.md.template
- tools/CONTRACT.md
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/instructions_cmd.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_instructions_cmd.py

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Code committed 2026-10-12 06:57:51 +02:00
1 parent c06bde2e95
commit 0f0a5799fd
16 files changed
+385 -54

No files matched your search

+23 -10
View File
@@ -160,7 +160,19 @@ Both targets are generated and gitignored. A fresh clone therefore has no skills
Copies, not symlinks: a symlink cannot go stale but is unreliable on Windows checkouts and
does not survive being archived or copied. The price of a copy is drift, and drift is what
`tools/wikitool instructions verify` checks - byte for byte against the source.
`tools/wikitool instructions verify` checks - against what `sync` would write from the source,
which is the source byte for byte plus one generated line.
That line is the instance's conversation language. When `kb/CONVENTIONS.md` declares a
`language:`, `sync` writes `> **Conversation language: \`de\`** - see \`AGENTS.md\` §
Conversation language ...` as the first paragraph under each published `SKILL.md`'s frontmatter,
so the value is in context when the task starts, not a file read away (the rule is
[AGENTS.md § Conversation language](../AGENTS.md#conversation-language); the line carries the
value and a pointer to it, not a second copy of the rule). Only `SKILL.md` gets it, in both
target directories, and its frontmatter and every other file of the skill stay byte-identical. With no
language declared the copy is the source unchanged. A skill's source never contains the line, and
changing `language:` makes `verify` and `doctor` report the copies as drifted, naming the line as
the reason; re-running `sync` repairs it.
## Writing an instruction
@@ -191,12 +203,13 @@ Scaffold with `tools/wikitool new instruction --name "<name>"`; the contract is
`instructions/migrations/` belong to the release they shipped with and are not rewritten. The
stack's own instructions are held to this by a test in the origin repository; what an instance
writes for itself is its own decision.
- **Write it in English, and let the agent speak the instance's language.** Both rules, and the
line between prose and quoted vocabulary, are stated once in
[AGENTS.md § File naming](../AGENTS.md#file-naming). They are named here because this is the
step where they are obeyed or lost: nothing checks either mechanically, and an instruction
that models a sentence for the user is where the two are easiest to confuse - the model is
written in English, the saying of it follows `kb/CONVENTIONS.md`'s `language:`.
- **Write it in English, and let the agent speak the instance's language.** The first rule, and
the line between prose and quoted vocabulary, are stated once in
[AGENTS.md § File naming](../AGENTS.md#file-naming), the second in
[AGENTS.md § Conversation language](../AGENTS.md#conversation-language). They are named here
because this is the step where they are obeyed or lost: nothing checks either mechanically, and
an instruction that models a sentence for the user is where the two are easiest to confuse -
the model is written in English, the saying of it follows `kb/CONVENTIONS.md`'s `language:`.
### A skill's H1 is a name, not an imperative
@@ -251,9 +264,9 @@ the next session to read before adding one.
### A skill's outbound reference is a plain path, not a link
`tools/wikitool instructions sync` copies each `SKILL.md` byte for byte into
`.agents/skills/<name>/` and `.claude/skills/<name>/` (§ Publishing, above) - a different depth
than the source, and without the sibling files a relative link might expect. A markdown link
`tools/wikitool instructions sync` copies each `SKILL.md` into
`.agents/skills/<name>/` and `.claude/skills/<name>/` (§ Publishing, above; the generated
language line it adds is no link) - a different depth than the source, and without the sibling files a relative link might expect. A markdown link
correct at `instructions/<name>/SKILL.md` (`../session-setup.md`, `../../kb/CONTRACT.md`)
resolves to a different, usually nonexistent, file once copied: the number of `../` segments
that reaches a target from `instructions/` does not reach the same target from