Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions (#129)
CI / verify (push) Successful in 51s
Release / release (push) Successful in 36s

Files changed:
- AGENTS.md
- CHANGES.md
- INSTALL.md
- README.md
- VERSION
- instructions/CONTRACT.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- instructions/gtd-weekly-review/SKILL.md
- instructions/setup-instance.md
- instructions/weekly-review/SKILL.md
- instructions/wiki-ingest/SKILL.md
- instructions/wiki-lint/SKILL.md
- instructions/wiki-manage/SKILL.md
- instructions/wiki-query/SKILL.md
- instructions/wiki-status/SKILL.md
- tools/chemenu/tests/test_instructions_cmd.py
This commit is contained in:
torben committed 2026-09-20 11:44:21 +02:00
1 parent 8ed8c6f5d9
commit 52ba5ba768
16 files changed
+71 -20

No files matched your search

+34
View File
@@ -18,6 +18,8 @@ alongside [AGENTS.md](../AGENTS.md).
- [Publishing](#publishing)
- [Writing an instruction](#writing-an-instruction)
- [A skill's H1 is a name, not an imperative](#a-skills-h1-is-a-name-not-an-imperative)
- [A skill's `description` speaks in third person](#a-skills-description-speaks-in-third-person)
- [A skill's name declares its family](#a-skills-name-declares-its-family)
- [A skill's outbound reference is a plain path, not a link](#a-skills-outbound-reference-is-a-plain-path-not-a-link)
- [Reference depth: bundled files, not repo-wide contracts](#reference-depth-bundled-files-not-repo-wide-contracts)
- [When a skill carries a copy-in checklist](#when-a-skill-carries-a-copy-in-checklist)
@@ -202,6 +204,38 @@ exception in the same breath - "for promoted skills, the skill name is the title
That is the whole exception. Everything else in this section binds a `SKILL.md` exactly as it
binds an instruction.
### A skill's `description` speaks in third person
Anthropic's skill-authoring guidance requires third person in a skill's `description`, because it
is injected into the system prompt for skill selection and an inconsistent point of view degrades
that selection - "Processes Excel files and generates reports", never "I can help you process..."
or "Process...". This binds every `instructions/<name>/SKILL.md` in this repo. The flat
`instructions/<name>.md` form's `description` (above) is read on demand rather than injected as
system-prompt metadata, so it keeps the imperative/label freedom that form already allows.
Nothing checks this mechanically - `tools/wikitool docs verify`/`instructions verify` validate a
`description`'s presence and length, not its grammatical voice - so it holds only as long as each
new skill is written to match the ones around it.
### A skill's name declares its family
Three prefixes exist today, each naming the subject domain a skill operates on, not the
distribution boundary it ships behind: `wiki-` for the knowledge pipeline (`wiki-ingest`,
`wiki-lint`, `wiki-manage`, `wiki-query`, `wiki-status`), `gtd-` for the commitment layer
(`gtd-weekly-review` - see `kb/gtd/COLLECTION.md` and `docs/knowledge-and-commitment.md` for why
that layer is named GTD rather than folded into `wiki-`), and `stack-` for the stack's own
development, nested under `instructions/dev/` and therefore never present in a distributed
instance (`instructions/dev/` above).
<!-- dist:strip-start -->
Dev-instance-only: the two skills in that family today are `stack-dev` and `stack-close`.
<!-- dist:strip-end -->
A new skill takes the prefix of the family it belongs to, or opens a new one deliberately - never
a bare name.
This is a convention, not something the tool enforces: an unprefixed or fourth-family name would
compile, publish and pass every check exactly like the three above, so it is written down here for
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