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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user