Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions (#129)
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
1 parent
8ed8c6f5d9
commit
52ba5ba768
16 files changed
+71
-20
No files matched your search
@@ -237,7 +237,7 @@ ships the first verbatim and the second only as a `.template`.
|
||||
| `wiki-manage` | A page needs creating, or new information needs integrating into one |
|
||||
| `wiki-lint` | The wiki needs a health check (also every 10 sources) |
|
||||
| `wiki-status` | A quick read-only snapshot is wanted, without a full lint |
|
||||
| `weekly-review` | `wikitool review` has findings nobody has acted on yet, or the user asks for the weekly review |
|
||||
| `gtd-weekly-review` | `wikitool review` has findings nobody has acted on yet, or the user asks for the weekly review |
|
||||
|
||||
Shared procedures that several skills call into: `tools/wikitool instructions list`.
|
||||
|
||||
|
||||
+18
-1
@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.
|
||||
|
||||
---
|
||||
|
||||
## 7.0.0-beta.8 - 2026-09-20 - docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates
|
||||
## 7.0.0-beta.9 - 2026-09-20 - Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
@@ -79,6 +79,7 @@ concern - readable here, never shipped as something to parse.
|
||||
**Low impact**
|
||||
- new project: Testabdeckung fuer die required-responsibility-Ablehnung
|
||||
- docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates
|
||||
- Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions
|
||||
<!-- /wikitool:bumps -->
|
||||
|
||||
### Typ `project` und Collection `kb/gtd/`: das Vorhaben als eigene Seitenart
|
||||
@@ -290,6 +291,22 @@ beide unpruefbar, weil eine `docs/`-Seite per Konstruktion keinen normativen Sat
|
||||
eine Gestalt, in der „das Upgrade schreibt diese Datei nie" zu Arbeit wird, mit Verweis auf den
|
||||
Schritt in `upgrade-instance.md`, den Stack 7.0.0-beta.7 dort angelegt hat.
|
||||
|
||||
### Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions
|
||||
|
||||
Gitea #129: the published skill collection had drifted into three naming shapes where it should
|
||||
have three *families*. `weekly-review` (added earlier in this same candidate, never released)
|
||||
named neither its domain nor its distribution boundary, unlike `wiki-*` and `stack-*` either
|
||||
side of it - renamed to `gtd-weekly-review`, joining a new `gtd-` prefix for the commitment layer
|
||||
(`kb/gtd/`, `types/project.md`, `docs/knowledge-and-commitment.md`) that sits beside `wiki-` (the
|
||||
knowledge pipeline) and `stack-` (the stack's own development, under `instructions/dev/`).
|
||||
`instructions/CONTRACT.md` § "Writing an instruction" now states both the family-prefix
|
||||
convention and, separately, that a skill's `description` speaks in third person per Anthropic's
|
||||
skill-authoring guidance - all eight published skills' descriptions were rewritten to match
|
||||
("Processes...", not "Process..."); the flat `instructions/<name>.md` form keeps its existing
|
||||
imperative-title convention, since its `description` is read on demand rather than injected into
|
||||
the system prompt. No `--breaking` line: the renamed skill was introduced by this same
|
||||
unreleased candidate, so no existing instance carries the old name to migrate away from.
|
||||
|
||||
---
|
||||
|
||||
## 6.2.0 - 2026-09-19 - Entity-Subtyp project nach codebase umbenannt
|
||||
|
||||
+1
-1
@@ -292,7 +292,7 @@ tools/wikitool version check
|
||||
```
|
||||
|
||||
**Aufgaben-Tracker anbinden - optional.** Der Wochenrückblick (`tools/wikitool review`, Skill
|
||||
`weekly-review`) gleicht die Projektseiten unter `kb/gtd/` gegen einen Aufgaben-Tracker ab. Welcher
|
||||
`gtd-weekly-review`) gleicht die Projektseiten unter `kb/gtd/` gegen einen Aufgaben-Tracker ab. Welcher
|
||||
das ist, steht in `.wikitool-tasks.json` im Repo-Root - der dritten Datei dieser Art neben
|
||||
`.wikitool-telemetry.json` und `.wikitool-remotes.json`: pro Checkout, ohne `.template`, und
|
||||
**gitignored, sobald ein Token darin liegt**. Fehlt sie, ist schlicht kein Tracker konfiguriert;
|
||||
|
||||
@@ -239,7 +239,7 @@ Nothing syncs between the two. `tools/wikitool review` joins them at read time
|
||||
over the project name and prints what needs a decision: initiatives with no next
|
||||
action, waiting-fors past their follow-up date, tracker projects with no page,
|
||||
active pages with no open loop, someday items gone stale. It stores nothing -
|
||||
not even a report file. The `weekly-review` skill then walks the findings with
|
||||
not even a report file. The `gtd-weekly-review` skill then walks the findings with
|
||||
you and turns each one into a decision; `tools/wikitool new project` is what
|
||||
gives a new initiative its page and its tracker project under one name.
|
||||
|
||||
@@ -280,7 +280,7 @@ themselves live as independently-discoverable skills under `.agents/skills/`
|
||||
| `wiki-lint` | Health-check the wiki: structural scan, raw coverage, semantic review |
|
||||
| `wiki-manage` | Create a new entity/concept/source/comparison page, or update an existing page with new information |
|
||||
| `wiki-status` | Read-only snapshot: page counts, orphans, uncovered raw files, most-connected pages |
|
||||
| `weekly-review` | Turn `wikitool review`'s findings into decisions and page updates - the GTD weekly review |
|
||||
| `gtd-weekly-review` | Turns `wikitool review`'s findings into decisions and page updates - the GTD weekly review |
|
||||
|
||||
Each skill's underlying mechanical work (frontmatter, cross-references, index/log,
|
||||
decay math, publishing) is delegated to `tools/wikitool` - never hand-edited.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: stack-close
|
||||
description: Close out a stack-dev work package after its publish has landed - rewrite the issue body to its final state, check for docs/ staleness, and name which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed.
|
||||
description: Closes out a stack-dev work package after its publish has landed - rewrites the issue body to its final state, checks for docs/ staleness, and names which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed.
|
||||
---
|
||||
|
||||
# Stack Close
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: stack-dev
|
||||
description: Switch a session into tool-development mode - extending tools/wikitool, the compiler, the type schema, or the instruction/skill layer itself, instead of operating on wiki content. Use when the user asks to add a wikitool command, change a type-spec, fix or extend the compiler, or otherwise work on the stack rather than ingest/query/manage/lint the wiki.
|
||||
description: Switches a session into tool-development mode - extending tools/wikitool, the compiler, the type schema, or the instruction/skill layer itself, instead of operating on wiki content. Use when the user asks to add a wikitool command, change a type-spec, fix or extend the compiler, or otherwise work on the stack rather than ingest/query/manage/lint the wiki.
|
||||
---
|
||||
|
||||
# Stack Development Mode
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: weekly-review
|
||||
description: Turn the findings from `wikitool review` into decisions and page updates - the GTD Weekly Review, with a machine that prepares the list instead of a human reconstructing it from memory. Use when the user asks for "the weekly review", "review my projects", "what's stalled", or after `wikitool review` has findings nobody has acted on yet.
|
||||
name: gtd-weekly-review
|
||||
description: Turns the findings from `wikitool review` into decisions and page updates - the GTD Weekly Review, with a machine that prepares the list instead of a human reconstructing it from memory. Use when the user asks for "the weekly review", "review my projects", "what's stalled", or after `wikitool review` has findings nobody has acted on yet.
|
||||
---
|
||||
|
||||
# Weekly Review
|
||||
# GTD Weekly Review
|
||||
|
||||
**Purpose:** A finding from `wikitool review` is not an action by itself - "this initiative looks
|
||||
stalled" can mean a next action is missing, the initiative was deliberately paused, or it is
|
||||
@@ -303,7 +303,7 @@ and ready for its first ingest.
|
||||
|
||||
16. **Restart the agent session.** Harnesses read the skill directories at startup; only
|
||||
afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint`, `wiki-status` and
|
||||
`weekly-review` available.
|
||||
`gtd-weekly-review` available.
|
||||
|
||||
## Scope
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: wiki-ingest
|
||||
description: Process a new source file into the LLM wiki - extract entities and concepts, create a source summary page, cross-reference, rebuild indexes, and publish. Use when the user drops a file into incoming/ or raw/, or says "ingest <file>", "process this source", "add this to the wiki".
|
||||
description: Processes a new source file into the LLM wiki - extracts entities and concepts, creates a source summary page, cross-references, rebuilds indexes, and publishes. Use when the user drops a file into incoming/ or raw/, or says "ingest <file>", "process this source", "add this to the wiki".
|
||||
---
|
||||
|
||||
# Wiki Ingest
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: wiki-lint
|
||||
description: Health-check the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references. Use when the user says "lint the wiki", "health-check the wiki", or periodically every 10 sources per the Maintenance Schedule.
|
||||
description: Checks the health of the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references. Use when the user says "lint the wiki", "health-check the wiki", or periodically every 10 sources per the Maintenance Schedule.
|
||||
---
|
||||
|
||||
# Wiki Lint
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: wiki-manage
|
||||
description: Create a new wiki page (entity, concept, source, comparison) or update an existing page with new information, including cross-references, index/log, and publish. Use when the user says "create a new entity/concept/comparison", "add a page for X", "update the X page", or new information needs integrating into an existing page.
|
||||
description: Creates a new wiki page (entity, concept, source, comparison) or updates an existing page with new information, including cross-references, index/log, and publishing. Use when the user says "create a new entity/concept/comparison", "add a page for X", "update the X page", or new information needs integrating into an existing page.
|
||||
---
|
||||
|
||||
# Wiki Manage
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: wiki-query
|
||||
description: Answer a question using the LLM wiki's compiled knowledge - read-only, cites sources, can file a valuable answer back as a new page. Use when the user asks a question about entities, projects, concepts, or anything the wiki might know, or says "query the wiki", "what do we know about X", "search the wiki".
|
||||
description: Answers a question using the LLM wiki's compiled knowledge - read-only, cites sources, can file a valuable answer back as a new page. Use when the user asks a question about entities, projects, concepts, or anything the wiki might know, or says "query the wiki", "what do we know about X", "search the wiki".
|
||||
---
|
||||
|
||||
# Wiki Query
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: wiki-status
|
||||
description: Show a quick read-only snapshot of the LLM wiki - page counts, orphan pages, uncovered raw files, recent activity. Use when the user says "wiki status", "show wiki statistics", "what's new", or wants a quick health snapshot without running a full lint.
|
||||
description: Shows a quick read-only snapshot of the LLM wiki - page counts, orphan pages, uncovered raw files, recent activity. Use when the user says "wiki status", "show wiki statistics", "what's new", or wants a quick health snapshot without running a full lint.
|
||||
---
|
||||
|
||||
# Wiki Status
|
||||
|
||||
@@ -75,13 +75,13 @@ def test_the_real_repo_publishes_the_six_wiki_skills():
|
||||
} <= names
|
||||
|
||||
|
||||
def test_weekly_review_skill_names_no_provider():
|
||||
def test_gtd_weekly_review_skill_names_no_provider():
|
||||
"""#119 D25/#127 AC1: the skill is the one document meant to read
|
||||
identically in every instance, whichever task-tracker provider it runs
|
||||
against - so its body must name none of them, and none of a provider's
|
||||
file or API shape either. Reads the real repo's file, not a fixture,
|
||||
because the claim is about what ships, not about the discovery logic."""
|
||||
text = (config.INSTRUCTIONS_DIR / "weekly-review" / "SKILL.md").read_text(encoding="utf-8").lower()
|
||||
text = (config.INSTRUCTIONS_DIR / "gtd-weekly-review" / "SKILL.md").read_text(encoding="utf-8").lower()
|
||||
forbidden = [
|
||||
"super productivity",
|
||||
"azure devops",
|
||||
@@ -91,7 +91,7 @@ def test_weekly_review_skill_names_no_provider():
|
||||
".wikitool-tasks.json",
|
||||
]
|
||||
hits = [term for term in forbidden if term in text]
|
||||
assert not hits, f"weekly-review/SKILL.md names a provider or its shape: {hits}"
|
||||
assert not hits, f"gtd-weekly-review/SKILL.md names a provider or its shape: {hits}"
|
||||
|
||||
|
||||
def test_instructions_dev_flat_file_is_discovered(layer):
|
||||
|
||||
Reference in new issue
Block a user