From 7bc6b7ae3ad5ee3d5b912646149ca772a45a09f1 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Fri, 19 Jun 2026 21:43:33 +0300 Subject: agent-task-management skill: make ask-is-not-NL warning prominent + add invocation contract Agents repeatedly mistook `ask` for a natural-language interface and ran things like `ask agent-task-management ...` or `ask `, forcing orchestrators to paste the correction into every task description. - Add a prominent STOP blockquote at the very top of SKILL.md stating that `ask` is a CLI with fixed subcommands and that agent-task-management is a skill name, never an `ask` subcommand. - Add an explicit 'Invocation contract' section listing the only valid form (`ask [args]`) and the real subcommands, derived from existing content; consolidate the valid/invalid examples there (DRY) with inline reasons on the invalid ones. - Mirror the same STOP warning at the top of references/00-context.md and tighten its rule to point at the contract. Co-Authored-By: Claude Opus 4.8 --- prompts/skills/agent-task-management/SKILL.md | 24 ++++++++++++++++------ .../agent-task-management/references/00-context.md | 8 +++++++- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/prompts/skills/agent-task-management/SKILL.md b/prompts/skills/agent-task-management/SKILL.md index cde2e9a..1d37c77 100644 --- a/prompts/skills/agent-task-management/SKILL.md +++ b/prompts/skills/agent-task-management/SKILL.md @@ -5,9 +5,19 @@ description: "Manage agent tasks scoped to the current git project using the `as # Agent Task Management -Tasks are scoped to the current git repository via the `ask` CLI. **Load only the files you need** for the current action so the whole skill does not need to be in context. +> **STOP — `ask` is a CLI with FIXED subcommands, NOT a natural-language interface.** +> It does not understand free text, sentences, or skill names. `agent-task-management` +> is the name of *this Claude skill* — it is **never** an `ask` subcommand. Do **not** run +> `ask agent-task-management …`, `ask `, or anything not in the invocation +> contract below. + +## Invocation contract + +The only valid form is `ask [args]`. The subcommands are: -The task CLI at `ask` provides subcommands (`list`, `ready`, `add`, `info`, `start`, `stop`, `done`, `annotate`, `modify`, `tag`, `priority`, `dep`, `delete`, `urgency`) that operate on agent-managed tasks in the current project. It is not a natural-language interface and does not understand skill names. Use normal subcommand syntax only. +`list`, `ready`, `add`, `info`, `start`, `stop`, `done`, `annotate`, `modify`, `tag`, `priority`, `dep`, `delete`, `urgency`. + +Anything not expressible as one of these subcommands is unsupported — do not improvise. Valid examples: @@ -20,13 +30,15 @@ Valid examples: - `ask annotate "progress note"` - `ask done ` -Invalid examples: +Invalid (will not work): -- `ask agent-task-management ...` -- `ask list tasks` -- `ask show task 298` +- `ask agent-task-management ...` ← skill name, not a subcommand +- `ask list tasks` ← `list` takes no natural-language object +- `ask show task 298` ← no `show` subcommand; use `ask info ` - any other natural-language phrasing passed to `ask` +Tasks are scoped to the current git repository via the `ask` CLI. **Load only the files you need** for the current action so the whole skill does not need to be in context. + **Alias IDs are the selectors to use for task work.** `ask add` prints `created task `, and subsequent task commands in this workflow should keep using that alias ID throughout the workflow. ## Context and compaction diff --git a/prompts/skills/agent-task-management/references/00-context.md b/prompts/skills/agent-task-management/references/00-context.md index c0598d8..a1dc47f 100644 --- a/prompts/skills/agent-task-management/references/00-context.md +++ b/prompts/skills/agent-task-management/references/00-context.md @@ -1,12 +1,18 @@ # Agent task management — shared context +> **STOP — `ask` is a CLI with FIXED subcommands, NOT a natural-language interface.** +> It does not understand free text, sentences, or skill names. `agent-task-management` +> is the name of *this Claude skill* — it is **never** an `ask` subcommand. Never run +> `ask agent-task-management …` or `ask `. Only `ask [args]` is +> valid (see the invocation contract in `SKILL.md`). + Load this with any of the action files (1–5) when working with tasks. It defines project scope and rules that apply to all task operations. ## Project name ## Rules that apply to all task commands -- **Always use `ask ` for all task operations.** The task CLI is installed at `~/go/bin/ask` and provides subcommands (`list`, `ready`, `add`, `info`, `start`, `stop`, `done`, `annotate`, `modify`, `tag`, `priority`, `dep`, `delete`, `urgency`) that operate on agent-managed tasks. It is not a natural-language interface and does not understand skill names. +- **Always use `ask ` for all task operations.** The task CLI is installed at `~/go/bin/ask` and provides exactly these subcommands: `list`, `ready`, `add`, `info`, `start`, `stop`, `done`, `annotate`, `modify`, `tag`, `priority`, `dep`, `delete`, `urgency`. It is not a natural-language interface and does not understand skill names; anything outside this subcommand list is wrong. - **Shell note:** Prefer `ask` (full path) so the correct binary is used regardless of `PATH`. The binary name is `ask` (not a zsh reserved word). - **One task in progress per project.** Do not start a second task while another is started and not completed, unless the user explicitly asks. - **Parallel work via sub-agents** — the agent may spawn sub-agents to work on tasks in parallel if those tasks would not conflict each other. -- cgit v1.2.3