// Use when a user-gate task has requiresUserSpecification=true OR the agent's "do I know HOW?" self-check returns no. Locks down verification mechanics through a short AskUserQuestion sequence and writes the answers back into the task's metadata. Does NOT run the verification itself.
Use when you have a spec or requirements for a multi-step task, before touching code
Use when picking up a user-gate task OR when a hook demands re-validation. Runs the "do I know HOW?" self-check; if the HOW is clear, executes the verification and posts evidence; if not, hands off to specifying-gates. Kept deliberately separate from executing-plans so that without the opt-in hook, the main flow stays untouched.
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when executing implementation plans with independent tasks in the current session
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
| name | specifying-gates |
| description | Use when a user-gate task has requiresUserSpecification=true OR the agent's "do I know HOW?" self-check returns no. Locks down verification mechanics through a short AskUserQuestion sequence and writes the answers back into the task's metadata. Does NOT run the verification itself. |
Exactly one of:
"requiresUserSpecification": true in its json:metadata fence, ORexecuting-plans) and concluded the verification mechanics are ambiguous, OR/specify-gate <task-id> manually.In all other cases — where verifyCommand is concrete and every acceptanceCriteria has an observable proof — the agent executes the gate directly and does NOT invoke this skill.
Announce at start: "I'm using the specifying-gates skill to lock down verification mechanics for Task N."
executing-plans afterward.The target task ID. Resolved from the command argument or from the currently-in-progress user-gate task.
Load the task with TaskGet and parse the json:metadata fence from its description.
Use AskUserQuestion — one question at a time per the brainstorming skill's rule.
AskUserQuestion:
question: "Gate: <task subject>. What exact state proves this works? One line per criterion. 'It works' is not an answer — name a sensor, HTTP status, log line, file presence, or equivalent."
header: "Gate outcome"
options:
- label: "I'll type the criteria"
description: "Write 1-5 concrete, observable conditions"
- label: "Copy from task's acceptanceCriteria"
description: "Use the existing list (only if it's already concrete)"
Store the user's free-text answer as a list of strings in acceptanceCriteria. If any entry is vague (contains "works", "fine", "as expected", "properly" without a concrete target), push back and ask them to name the observable.
AskUserQuestion:
question: "How should the agent capture that state?"
header: "Mechanism"
options:
- label: "CLI command"
description: "A shell command whose output shows the criterion"
- label: "REST / API call"
description: "HTTP request, inspect response"
- label: "Subagent with briefing"
description: "Dispatch Sonnet or Haiku with a prompt template"
- label: "Direct inspection"
description: "Read a file, query an entity, check a log"
If "Subagent with briefing" → ask Q5 (dispatch contract) before proceeding.
AskUserQuestion:
question: "Run this once, or over multiple targets?"
header: "Scope"
options:
- label: "Once"
description: "Single execution, single target"
- label: "Per instance / target"
description: "Run identically across a list (e.g. all environments)"
- label: "First on one, then on all"
description: "Prove it on one target, then roll out to the rest — the classic two-gate pattern"
- label: "Custom"
description: "Describe the rule in free text"
Store as gateScope: "once" | "per-target" | "one-then-all" | custom string.
AskUserQuestion:
question: "If the gate fails, what happens?"
header: "On failure"
options:
- label: "Stop the plan (Recommended)"
description: "No further tasks until this gate passes"
- label: "Reopen this task, continue others"
description: "Mark in_progress, keep the plan moving elsewhere"
- label: "Log and continue"
description: "Record failure, proceed — use only for informational gates"
Store as failurePolicy: "stop-plan" | "reopen-continue" | "log-continue".
Only when Q2 = "Subagent with briefing".
AskUserQuestion:
question: "Paste the exact prompt / briefing the subagent should receive. This becomes the dispatch contract — the agent cannot substitute a shorter version at runtime."
header: "Dispatch brief"
options:
- label: "I'll paste it"
description: "Provide the briefing text"
- label: "Use instances/<tag>/seed-briefing.md"
description: "Per-target briefing file already written by a plan task"
- label: "Generate from task description"
description: "Build the briefing from the task's Goal + Files + Acceptance Criteria"
Store as subagentBrief (string or file-path).
After all questions answered:
json:metadata fence with the new fields. Remove requiresUserSpecification. Keep everything else. Call TaskUpdate with the full new description.{
"files": [...],
"verifyCommand": "<from Q2 — the CLI/API string, or '(subagent)' sentinel>",
"acceptanceCriteria": ["<from Q1>", ...],
"userGate": true,
"tags": ["user-gate"],
"gateScope": "<from Q3>",
"failurePolicy": "<from Q4>",
"subagentBrief": "<from Q5 if applicable>"
}
json:metadata fence:### Specification (via /specify-gate on <ISO-date>)
- **Outcome:** <Q1>
- **Mechanism:** <Q2>
- **Scope:** <Q3>
- **Failure policy:** <Q4>
- **Subagent brief:** <Q5 if applicable>
Sync .tasks.json. Update the task entry's description and metadata, set lastUpdated.
Announce: "Specification locked. Returning control to executing-plans to run the gate."
Control returns to executing-plans. The agent reads the updated task, executes verifyCommand (or dispatches the subagent with subagentBrief), captures output, and posts AC: <criterion> — PROVEN BY <evidence> per criterion before closing.
ExitPlanMode or EnterPlanMode.executing-plans after this skill exits..tasks.json. No side files.executing-plans (automatic), /specify-gate slash command (manual).executing-plans.skills/shared/task-format-reference.md for metadata schema.